---

name: sap-gui-scripting description: Comprehensive SAP GUI automation for end-user task automation including connection/session management, transaction execution, GUI element interaction, table/tree operations, and script recording assistance. Use when working with SAP GUI for Windows to automate repetitive tasks, extract data, or navigate transactions programmatically.

SAP GUI Scripting Skill

Automate SAP GUI tasks using Python or VBScript. This skill provides scripts, templates, and reference documentation for all levels of SAP GUI scripting.

Quick Start

Basic Connection (Working Pattern)

IMPORTANT: Use GetObject("SAPGUI") pattern, NOT Dispatch("SapGui.Scripting.1") which fails in many environments.

from win32com.client import GetObject
import time

# Connect using GetObject (CORRECT)
SapGuiAuto = GetObject("SAPGUI")
application = SapGuiAuto.GetScriptingEngine
connection = application.OpenConnection("SYSTEM_NAME", True)
session = connection.Children(0)

# Wait for login screen
time.sleep(3)

# Login
session.FindById("wnd[0]/usr/txtRSYST-BNAME").Text = "USERNAME"
session.FindById("wnd[0]/usr/pwdRSYST-BCODE").Text = "PASSWORD"
session.FindById("wnd[0]").SendVKey(0)

# Handle multiple logon popup (if another session exists)
try:
    if session.FindById("wnd[1]").Name != "":
        session.FindById("wnd[1]/tbar[0]/btn[1]").Press()  # End other sessions
except:
    pass

# Execute transaction
session.FindById("wnd[0]/tbar[0]/okcd").Text = "/nME23N"
session.FindById("wnd[0]").SendVKey(0)

Using Helper Module

from scripts.connection.sap_connection import (
    connect_by_system_name, login, handle_multiple_logon
)

# Connect and login
session = connect_by_system_name("PRD")
login(session, "USERNAME", "PASSWORD")
handle_multiple_logon(session)

# Execute transaction
session.FindById("wnd[0]/tbar[0]/okcd").Text = "/nME23N"
session.FindById("wnd[0]").SendVKey(0)

Level 1: Basic Operations

Connection Management

File: scripts/connection/sap_connection.py

from scripts.connection.sap_connection import (
    SAPConnection, connect, connect_by_system_name, 
    login, handle_multiple_logon, export_to_sap_dialog
)

# Method 1: Simple connection (recommended)
session = connect_by_system_name("PRD")
login(session, "USERNAME", "PASSWORD")
handle_multiple_logon(session)

# Method 2: Using class with auto-login
conn = connect("PRD", "100", "USER123", "password123")
session = conn.session

# Method 3: Using class for more control
sap_conn = SAPConnection()
session = sap_conn.connect_by_name("PRD")
sap_conn.login("100", "USER123", "password123")
sap_conn.handle_multiple_logon()

# Method 4: From environment variables
# Set SAP_SYSTEM, SAP_CLIENT, SAP_USER, SAP_PASSWORD
conn = connect_from_env()

# Get session info
info = sap_conn.get_session_info()
print(f"User: {info['user']}, Transaction: {info['transaction']}")

Multiple Logon Popup

When multiple SAP sessions exist for the same user, SAP shows a popup:

• btn[0]: Continue with this logon (keep other sessions)
• btn[1]: Continue with this logon and end any other logons
• btn[2]: Cancel

# Always handle after login
handle_multiple_logon(session)

# Or use class method
sap_conn.handle_multiple_logon()

Export to File (SAP Dialog)

from scripts.connection.sap_connection import export_to_sap_dialog

# After running a report with ALV grid
export_to_sap_dialog(session, "my_report", r"C:\Output", open_excel=False)

VBScript Template: scripts/connection/sap_connection.vbs

---

Session Management

File: scripts/connection/session_manager.py

from scripts.connection.session_manager import create_session_manager

mgr = create_session_manager(session)

# Create new session
new_session = mgr.create_session()

# Get all sessions
sessions = mgr.get_all_sessions()

# Switch to session
session = mgr.switch_to_session(0)

# Close session
mgr.close_session()

---

Element Finding

File: scripts/elements/element_finder.py

from scripts.elements.element_finder import create_element_finder

finder = create_element_finder(session)

# By ID
element = finder.find_by_id("wnd[0]/usr/txtRSYST-BNAME")

# By name
element = finder.find_by_name("RSYST-BNAME")

# All input fields
input_fields = finder.find_input_fields()

# All buttons
buttons = finder.find_buttons()

# Find by text
element = finder.find_by_text("Save")

# Print element tree (debugging)
finder.print_element_tree()

---

Text Input

File: scripts/elements/input_handler.py

from scripts.elements.input_handler import create_input_handler

input_h = create_input_handler(session)

# Set text
input_h.set_text("wnd[0]/usr/ctxtEBELN", "4500012345")

# Get text
value = input_h.get_text("wnd[0]/usr/ctxtEBELN")

# Clear field
input_h.clear_field("wnd[0]/usr/ctxtEBELN")

# Focus field
input_h.focus_field("wnd[0]/usr/ctxtEBELN")

# Send keys
input_h.send_enter()
input_h.send_function_key(4)  # F4 for search help

---

Button Clicks

File: scripts/elements/click_handler.py

from scripts.elements.click_handler import create_click_handler

click_h = create_click_handler(session)

# Press button
click_h.press_button("wnd[0]/tbar[1]/btn[0]")

# Check if enabled
if click_h.is_button_enabled("wnd[0]/tbar[1]/btn[0]"):
    click_h.press_button("wnd[0]/tbar[1]/btn[0]")

# Checkboxes
from scripts.elements.click_handler import create_checkbox_handler
checkbox = create_checkbox_handler(session)
checkbox.select("wnd[0]/usr/chkEKKO-LEWRT")
is_checked = checkbox.is_selected("wnd[0]/usr/chkEKKO-LEWRT")

---

Transaction Execution

File: scripts/utils/transaction_manager.py

from scripts.utils.transaction_manager import create_transaction_manager

txn = create_transaction_manager(session)

# Execute transaction
txn.execute("ME23N")

# With parameters
txn.execute("ME23N", {
    "wnd[0]/usr/ctxtEBELN": "4500012345"
})

# Navigation
txn.navigate_back()      # F3
txn.navigate_exit()      # Shift+F3
txn.refresh()            # F5
txn.cancel()             # F12

# Get current transaction
current = txn.get_current_transaction()

---

Level 2: Intermediate Operations

Table Operations

Files: scripts/tables/table_reader.py

from scripts.tables.table_reader import (
    create_table_reader, create_table_writer, create_table_exporter
)

reader = create_table_reader(session)
writer = create_table_writer(session)
exporter = create_table_exporter(session)

# Read table control
data = reader.read_table_control("wnd[0]/usr/tblSAPLMEREQ_TC_TOTAL")

# Read ALV grid
data, columns = reader.read_alv_grid("wnd[0]/usr/cntlGRID1/shellcont/shell")

# Get row count
row_count = reader.get_row_count("wnd[0]/usr/tblTABLE")

# Find row by value
row_idx = reader.find_row_by_value("wnd[0]/usr/tblTABLE", 0, "4500012345")

# Write to table
writer.set_cell("wnd[0]/usr/tblTABLE", 0, 1, "NEW_VALUE")

# Export to CSV
exporter.to_csv("wnd[0]/usr/tblTABLE", "data.csv")

# Export to Excel
exporter.to_excel("wnd[0]/usr/tblTABLE", "data.xlsx")

---

Tree Operations

Files: scripts/trees/tree_navigator.py

from scripts.trees.tree_navigator import create_tree_navigator, create_tree_searcher

navigator = create_tree_navigator(session)
searcher = create_tree_searcher(session)

# Expand/collapse nodes
navigator.expand_node("wnd[0]/usr/treeTREE", "NODE_KEY")
navigator.collapse_node("wnd[0]/usr/treeTREE", "NODE_KEY")

# Select node
navigator.select_node("wnd[0]/usr/treeTREE", "NODE_KEY")

# Double-click
navigator.double_click_node("wnd[0]/usr/treeTREE", "NODE_KEY")

# Get selected
selected = navigator.get_selected_node("wnd[0]/usr/treeTREE")

# Find by text
node_key = searcher.find_by_text("wnd[0]/usr/treeTREE", "Node Text")

# Expand path
searcher.expand_path("wnd[0]/usr/treeTREE", "Root/Child/Grandchild")

---

Wait Strategies

File: scripts/utils/wait_strategies.py

from scripts.utils.wait_strategies import create_wait_strategies

wait = create_wait_strategies(session)

# Wait for element
element = wait.wait_for_element("wnd[0]/usr/ctxtEBELN", timeout=30)

# Wait for enabled
element = wait.wait_for_element_enabled("wnd[0]/tbar[1]/btn[0]", timeout=10)

# Wait for status bar clear
status = wait.wait_for_status_bar_clear(timeout=30)

# Wait for busy to clear
wait.wait_for_busy_clear(timeout=60)

# Wait and click
wait.wait_and_click("wnd[0]/tbar[1]/btn[0]", timeout=30)

# Exponential backoff
result = wait.exponential_backoff_wait(
    lambda: session.FindById("wnd[0]/usr/ctxtEBELN").Text,
    max_retries=5
)

---

Error Handling

File: scripts/utils/error_handler.py

from scripts.utils.error_handler import create_error_handler, create_retry_handler

error_h = create_error_handler(session)
retry_h = create_retry_handler(session)

# Check status bar
msg = error_h.get_status_bar_message()
if msg['type'] == 'E':
    print(f"Error: {msg['text']}")

# Raise on error
error_h.raise_on_error("Custom error message")

# Handle popup
result = error_h.handle_popup({'YES': 'btnYES'})

# Press OK on errors
error_h.press_ok_on_errors()

# Retry with backoff
result = retry_h.retry_operation(
    lambda: session.FindById("wnd[0]/usr/ctxtEBELN").Text,
    max_retries=3,
    delay=2
)

# Retry on error
result = retry_h.retry_on_error(
    lambda: txn.execute("ME23N"),
    error_codes=['E', 'A']
)

---

Level 3: Advanced Operations

Batch Processing

File: scripts/advanced/batch_processor.py

from scripts.advanced.batch_processor import create_batch_processor

batch = create_batch_processor(session)

# Run transaction sequence
results = batch.run_transaction_sequence(
    transactions=["ME23N", "ME22N", "ME21N"],
    continue_on_error=True
)

# Process items
items = ["450001", "450002", "450003"]
results = batch.process_items(
    items,
    lambda item: session.FindById("wnd[0]/usr/ctxtEBELN").Text,
    batch_size=10
)

# Get summary
summary = batch.get_summary()
print(f"Success: {summary['successful']}, Failed: {summary['failed']}")

---

Background Execution

File: scripts/advanced/background_runner.py

from scripts.advanced.background_runner import (
    create_background_runner, connect_invisible
)

# Method 1: Hide existing SAP window
runner = create_background_runner()
runner.hide_sap_window()
# ... run operations ...
runner.show_sap_window()

# Method 2: Connect invisibly
sap = connect_invisible("PRD")
# ... run operations ...
sap.close()

# Interactive mode (temporary visibility)
with sap.interactive_mode():
    # Window is visible here for user interaction
    pass
# Window hidden again

---

Screenshot Capture

File: scripts/advanced/screenshot_capture.py

from scripts.advanced.screenshot_capture import create_screenshot_capture

capture = create_screenshot_capture(session)

# Capture screenshot
filename = capture.capture_window()

# Capture on error (context manager)
with capture.capture_on_error("ME23N_operation"):
    txn.execute("ME23N")

# Capture element tree
capture.capture_element_tree("element_tree.txt")

# Capture status bar
capture.capture_status_bar("status_bar.txt")

# Capture session info
capture.capture_session_info("session_info.txt")

---

Reference Documentation

Object Model

See: references/object_model.md

Complete hierarchy: GuiApplication → GuiConnection → GuiSession → GuiWindow → GuiUserArea → GuiShell → GUI elements

Element Types

See: references/element_types.md

40+ element types: GuiTextField, GuiButton, GuiCheckBox, GuiComboBox, GuiTableControl, GuiTree, GuiGridView, etc.

Recording Guide

See: references/recording_guide.md

1. Enable scripting in SAP GUI Options
2. Run /nSCR or right-click → Script Recording
3. Record actions, export as VBScript
4. Convert to Python using patterns from VBScript reference

VBScript Reference

See: references/vbscript_reference.md

Native SAP GUI scripting syntax for direct playback

Error Codes

See: references/error_codes.md

Common SAP errors and handling patterns

Best Practices

See: references/best_practices.md

Performance, reliability, security, and code organization patterns

---

Sample Scripts

Login and Execute Transaction

assets/sample_scripts/login_to_sap.py

Run Any Transaction

assets/sample_scripts/run_transaction.py

Extract ALV Report

assets/sample_scripts/extract_alv_report.py

VA05 Sales Order Export (VBScript)

scripts/examples/va05_export.vbs - Complete working example with connection, login, multiple logon handling, and export

---

VBScript Templates

• scripts/connection/sap_connection.vbs - Connection template with login and multiple logon handling
• scripts/connection/session_manager.vbs - Session management
• scripts/elements/element_finder.vbs - Element operations
• scripts/tables/table_reader.vbs - Table operations
• scripts/trees/tree_navigator.vbs - Tree operations
• scripts/utils/wait_strategies.vbs - Wait and delay functions
• scripts/examples/va05_export.vbs - Complete VA05 export example

---

Prerequisites

1. SAP GUI for Windows (7.50 or higher recommended)
2. Python (3.8+)
3. pywin32 library: pip install pywin32
4. Optional: openpyxl for Excel export: pip install openpyxl
5. Enable scripting in SAP GUI:
   • Options -> Accessibility & Scripting -> Scripting -> Enable Scripting

---

Common Element IDs

| Element | ID Pattern | |---------|-----------| | Main window | wnd[0] | | Popup window | wnd[1] | | User area | wnd[0]/usr | | OK code field | wnd[0]/tbar[0]/okcd | | Standard toolbar | wnd[0]/tbar[0] | | Application toolbar | wnd[0]/tbar[1] | | Menu bar | wnd[0]/mbar | | Status bar | wnd[0]/sbar | | ALV Grid | wnd[0]/usr/cntlGRID1/shellcont/shell |

---

Troubleshooting

"Invalid class string" or connection fails:

• Use GetObject("SAPGUI") pattern, NOT Dispatch("SapGui.Scripting.1")
• Ensure SAP GUI is running before connecting

"Element not found" error:

• Use the recorder (/nSCR) to get correct element IDs
• Check screen number in ID (wnd[0] vs wnd[1] for popups)
• Add delay after transactions: time.sleep(2)

Multiple logon popup blocks script:

• Always call handle_multiple_logon(session) after login
• The popup appears when user has other active sessions

Scripting not enabled:

• Enable in SAP GUI Options -> Accessibility & Scripting -> Enable Scripting
• Server-side: Set sapgui/user_scripting = TRUE in RZ11

"Object variable not set":

• Ensure proper connection before accessing session
• Check if SAP is already logged in
• Add time.sleep(3) after opening connection

Export dialog issues:

• Uncheck "Open with Excel" checkbox if not needed
• Element IDs may vary by SAP version - use recorder to verify

Performance issues:

• Use background execution for batch operations
• Implement wait strategies instead of fixed delays
• Use SAP's native export dialog for large datasets