---

name: sap-windowsgui-logon description: Log on to a locally installed SAP GUI for Windows system from a JSON configuration, preferring pywin32 with SAP GUI Scripting and automatically falling back to sapshcut.exe when scripting is unavailable before credentials are submitted. Use when Codex needs to validate an SAP GUI logon configuration, start an SAP Logon connection, handle a server with GUI Scripting disabled, or authenticate a user through either supported method.

SAP Windows GUI Logon

Use the bundled PowerShell launcher backed by scripts/logon.py. It selects between pywin32 SAP GUI Scripting and SAP Shortcut; do not reimplement the login with keystrokes, OCR, window titles, or fixed screen coordinates.

Required Workflow

1. Use %USERPROFILE%\.sap-windowsgui-logon\config.json unless the user provides another configuration path.

2. If the configuration does not exist, copy assets/config.example.json to that location and ask the user to fill it locally. Never ask the user to paste a password into chat.

3. Do not read, print, summarize, or pass configuration values on the command line. Pass only the configuration file path to the script.

4. Validate the configuration before a first live login:

   powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/logon.ps1 -ValidateOnly
   

5. Run the live login after validation:

   powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/logon.ps1
   

6. Add -ConfigPath "<LOCAL_CONFIG_PATH>\config.json" only for a non-default configuration. Add -SapLogonPath or -SapShcutPath only when the executables cannot be discovered automatically.

7. Use the automatic SAP Shortcut fallback by default. Add -DisableSapshcutFallback only when the user rejects command-line password exposure.

8. Report the selected method and whether authentication was verified. Never expose the password or the full configuration content.

Configuration Contract

The JSON file must contain the following required string fields:

• Description: exact, case-sensitive SAP Logon connection description.
• Client: three-digit SAP client, including leading zeros.
• User: SAP user name.
• Password: SAP password. Preserve leading or trailing characters.
• LogonLanguage: two-letter SAP logon language such as EN, DE, or ZH.

System is optional. Set it to the three-character SAP system ID when Description cannot be mapped uniquely through %APPDATA%\SAP\Common\SAPUILandscape.xml for the SAP Shortcut fallback.

Store the configuration outside the repository and restrict its NTFS permissions to the intended Windows user. The script never writes the configuration or logs its contents.

Automation Rules

• Require Windows, SAP GUI for Windows, Python 3.11 or later, and pywin32>=311.
• Keep scripts/requirements.txt pinned to the tested baseline. The logon script accepts installed dependency versions that meet or exceed the minimum and runs the normal validation or login first. If that flow fails while the installed dependency version differs from the tested baseline, report both versions and recommend reproducing with scripts/requirements.txt.
• Try pywin32 SAP GUI Scripting first. Select the connection through OpenConnection(Description), fill the login screen through SAP technical control IDs, and verify the authenticated client and user.
• Fall back only when Scripting is unavailable before credential submission, the server returns DisabledByServer, or no scriptable session/login controls become available.
• Before fallback, close the incomplete scripting connection when possible, resolve Description to a system ID, and launch sapshcut.exe with system, client, user, password, and language arguments.
• Never fall back after credentials were submitted, after SAP rejects a login, or when a secondary dialog appears.
• Treat SAP Shortcut success as launched but unverified because disabled Scripting prevents reading the authenticated session.
• Warn that SAP Shortcut places the password in the child process command line for a short period. Never print or log the command.
• Wait for SAP GUI and its login controls instead of using fixed sleeps as success criteria.
• Stop if SAP displays a secondary dialog after credential submission. Do not guess how to resolve multiple-logon, password-change, license, or security dialogs.
• Do not retry a rejected password automatically; repeated attempts can lock the SAP account.
• Treat the configuration file as sensitive even when validation fails.

Result Contract

Scripting success means the created SAP session reports the requested client and a non-empty authenticated user. SAP Shortcut success means sapshcut.exe accepted the request, but authentication remains unverified. A validation-only run verifies configuration shape without starting or controlling SAP GUI. Any missing prerequisite, mapping error, rejected login, secondary dialog, or executable failure returns a nonzero exit code and leaves SAP windows available for manual inspection.