What Should a Person Still Guard When an Agent Drives SAP GUI?

A coding agent connected through ADT can read and change ABAP source and query tables with SQL. ADT reaches objects. Opening a transaction, entering values, and running something like automatic payment in F110 still happen in SAP GUI. SAP GUI Scripting lets the agent drive those screens too, and that creates places where a person has to stand guard. This note walks through those places in order and shows how to close each one with code and rules.

The case used here is a made-up example for explanation. The fictional Company A, the test system TST with client 400, vendor 100100, and every amount are invented. Nothing here comes from a real company’s system. The screen images and code are illustrations, not captures or results from a real system.

• A person logs on. The agent attaches only to an SAP GUI session that is already open. The password never passes through the agent.
• Production sessions are display only, and writes happen only on a QA client chosen in advance. The script enforces it by picking its session by system and client.
• Steps that are hard to undo, such as a security prompt, a payment run, or the reply to the requester, are a person’s to press.
• A first answer built from display data is an inference. Write the procedure a person will follow only after the screens have been opened in QA.

The agent attaches to a GUI a person already opened

SAP NOTES

The agent attaches to an open GUI

A person logs in. The script drives the screen.

1. 01

   Person

   • A person logs on to SAP
   • The password never reaches the agent
2. 02

   Script

   • cscript runs a VBScript
   • COM attaches to the running SAP Logon
3. 03

   Session

   GetObject("SAPGUI")

   • GuiApplication, GuiConnection, GuiSession
   • Screen elements are found with findById
4. 04

   Boundary

   • Production sessions stay on display transactions
   • Writes use only a chosen QA client

A generic setup, not any particular system.

The setup is small. The agent runs a VBScript through cscript on the PC, and the script attaches to the running SAP Logon with COM. Calling GetScriptingEngine on GetObject("SAPGUI") returns the GuiApplication, and under it are the connections (GuiConnection) and sessions (GuiSession). Screen elements are found with findById. Here is a minimal example that lists the open sessions by system and client.

Set app = GetObject("SAPGUI").GetScriptingEngine
For Each conn In app.Children
  For Each s In conn.Children
    WScript.Echo s.Info.SystemName & "/" & s.Info.Client
  Next
Next

• Do not let the script open a new connection with OpenConnection. A new connection often starts at the logon screen, which opens a path for handing account details to the script.
• Python can use the same COM objects through pywin32. VBScript needs no extra install, but Microsoft has announced that it will be phased out.
• cscript writes console output in the console code page, CP949 by default on Korean Windows, so Korean text can break when the reader expects UTF-8. Write results to a UTF-8 file with ADODB.Stream and let the agent read that file.
• Check values changed through the GUI again with a database query. A “saved” message on the screen is not the end of it.

Scripting has to be on at the server and the client

SAP NOTES

Scripting has to be on at both ends

Check the client, the server and the attached session separately

• Client

  • Enable scripting in SAP GUI Options and the registry value UserScripting
  • A person decides whether the notices stay on

• Server

  • sapgui/user_scripting, off by default
  • A change in RZ11 applies from the next logon

• The attached session

  • GuiConnection.DisabledByServer
  • ScriptingModeReadOnly in the session info

• If production has it on

  • Display transactions such as SE16N and FB03 only
  • Review read-only and per-user modes with Basis

A parameter history table records past values. It does not replace the current value.

On the client, scripting is turned on in SAP GUI Options under Accessibility & Scripting, Scripting. The setting is the UserScripting value under HKEY_CURRENT_USER\SOFTWARE\SAP\SAPGUI Front\SAP Frontend Server\Security. If an administrator sets the value under HKEY_LOCAL_MACHINE to 0, users cannot turn it on. The two notices, for when a script attaches and when it opens a connection, are WarnOnAttach and WarnOnConnection.

The notices protect against scripts running without the user knowing. Turning them off means fewer stops, but a person decides that, and the agent is not allowed to edit the registry. When a script stops with The control could not be found by id, usually the screen it expected and the screen in front of it differ, so check first for an open notice or confirmation window, or a changed screen.

The server switch is the profile parameter sapgui/user_scripting. It is off by default, and it has to be TRUE before scripts run against sessions on that application server. From release 6.20 on it can be changed in RZ11 without restarting the server, and the new value applies from the next logon to that server. A value changed in RZ11 reverts to the profile value when the instance restarts. It can be set per application server, so the same system can give different answers depending on the server you logged on to.

RZ11 shows the current value, but whether the session the agent attached to is really allowed is best read from that session. GuiConnection.DisabledByServer is True when scripting has not been enabled on that application server. ScriptingModeReadOnly in the session info (GuiSessionInfo) tells whether read-only mode is on. A parameter history table such as PAHI holds values as they were recorded, so it does not prove the current value on the server you are attached to.

For Each conn In app.Children
  WScript.Echo conn.Description & " server-disabled=" & conn.DisabledByServer
  If Not conn.DisabledByServer Then
    For Each s In conn.Children
      WScript.Echo "  " & s.Info.SystemName & "/" & s.Info.Client _
        & " read-only=" & s.Info.ScriptingModeReadOnly
    Next
  End If
Next

The server also has parameters that narrow the scope. They take effect only after sapgui/user_scripting is on, and each has its own release requirements. If production must have scripting on, choose among them with the Basis team.

• sapgui/user_scripting_set_readonly: scripts can read properties and call read-only functions only. Calls that change the screen state sent to the server are blocked, even when no database update would follow.
• sapgui/user_scripting_per_user: after logon, only users with the Execute (16) authorization of authorization object S_SCR keep scripting.
• sapgui/user_scripting_force_notification: each time a script tries to use a connection to that system, the user is asked whether to allow it.
• sapgui/user_scripting_disable_recording: turns off scripting events, so new recordings are not possible. Existing scripts still run.

If scripts can run against production sessions, that is convenient and risky, so write the rules first. In production sessions, open only display transactions such as SE16N and FB03, and never press anything that saves, posts or schedules a run. Writes happen only on a QA client chosen in advance. Put the rule in code as well as in a document: a write script picks its session by system and client at the start, and ends if no matching session exists.

Narrowing the cause with display only

Suppose an accounts payable clerk at the fictional Company A asks this. Vendor 100100 has three invoices (KRW 500,000, KRW 400,000 and KRW 300,000) and one credit memo (KRW 200,000). When automatic payment (F110) runs, only the invoices are paid and the credit memo is not deducted.

In production, the agent only displays. It reads the payment-related fields of the four documents in SE16N or FB03. The fields to read first are payment block (ZLSPR), payment method (ZLSCH), baseline date (ZFBDT) and payment terms (ZTERM), partner bank type (BVTYP), and house bank (HBKID). A script reading screens can fall into a few traps here.

SE16N can hide columns. With a default ALV layout set for the user, the result grid shows only some columns. ColumnOrder on the grid object GuiGridView gives the identifiers of the columns currently displayed, in order. If a field is missing, suspect the layout before the data.

Do not rely on selection-row numbers. The SE16N selection screen shows a fixed number of rows, and the field order differs by table. Find the field by its technical name and type into that row.

Reading cell by cell is slow. Reading an ALV grid with GetCellValue one cell at a time makes one COM call per cell, and the time grows quickly with rows and columns. Read only the columns you need and tighten the selection. For output shown as a classic ABAP list, such as the F110 proposal list, save it to a file with the OK code %pc and let the agent read the file.

A popup is another window. Screens that open as popups, such as confirmation or extra-input windows, are wnd[1] or later. Capturing only wnd[0] keeps just the screen behind the popup.

SAP NOTES

Where an item drops out of the proposal

Four places, shown with fictional vendor 100100

• Payment block

  • A payment block key on the item (ZLSPR)
  • A payment block on the vendor master

• Payment method and bank

  • A payment method that is not in the parameters
  • No matching vendor bank details

• Due date and entry date

  • Not due before the next payment date, so it waits for the next run
  • Docs entered up to filters on the entry date CPUDT

• Grouping and balance

  • One payment needs matching values such as currency, payment method, BVTYP and HBKID
  • A group with only the credit memo is a debit balance and becomes an exception

A fictional example. The vendor number and values are made up, not a real payment record.

F110 selects open items, groups them into payments, and assigns payment methods and banks. The places an item fails to be paid usually fall into four groups.

• Payment block. A payment block key on the item, or a payment block on the vendor master, keeps it from being paid, and it shows up in the proposal’s exception list or log.
• Payment method and bank details. If the payment methods entered in the parameters do not match the item’s or the vendor master’s payment method, or the vendor bank details that the method needs are missing, the item gets no payment method.
• Due date and entry date. An item that does not fall due before the next payment date waits for the next run. The “Docs entered up to” parameter filters on the entry date (CPUDT), not the posting date. A credit memo without an invoice reference (REBZG) is due on its baseline date, whatever the payment terms.
• Grouping and balance. Items with the same values for currency, payment method, partner bank type (BVTYP), house bank (HBKID) and the like become one payment. If the vendor master has a grouping key, the fields that key names split groups too. With Pay all items separately set on the vendor master, every item is paid on its own. If the credit memo ends up in a group of its own, that group has a debit balance, cannot be paid, and stays an exception.

Suppose that in the fictional example the cause is grouping. Only the credit memo carries BVTYP 0002; the three invoices have it blank. The three invoices then become one payment, and the credit memo is grouped alone and left as a debit balance. That matches the symptom the clerk described.

To confirm a cause, turn on the due-date check and payment-method selection logs on F110’s Additional Log tab, enter only that vendor both in the tab’s account range and in the parameters, and run the proposal. The log records why an item dropped out. A proposal posts no documents, but it still runs a job, so a person decides whether to run it in production, and the agent runs it in QA.

Check the entry date as well. It is stamped with the application server’s date, not the local date of the person entering. For example, if the server’s time zone is eight hours ahead of the clerk’s, a document entered from 16:00 the clerk’s time carries the next day as its server date. Put the local date into “Docs entered up to”, run a same-day payment, and that document is left out.

Where a first answer tends to go wrong

A first answer written from display data alone can get the cause right and the procedure wrong. In the fictional example, a first answer could look like one of these.

1. “Remove BVTYP from the credit memo in FB02.” The field may not be open on the FB02 screen. The field status of the item is set by the posting key together with the field status group of the reconciliation account, and which fields can change after posting is set by the document change rules. If a person will follow the procedure, first check on screen that the field actually opens.
2. “QA has no matching data.” ABAP SQL reads only the logon client’s data by default. If the ADT project is logged on to another client, the data looks missing. Check the logon client, and name the client with USING CLIENT when needed.
3. “Clear the items and set the value right on the residual item.” A residual item is a new item. Do not assume that its posting key, bank fields or payment block match the original. What a new item carries depends on the system’s settings. Open the new item in FB03 and check.

Even after several rounds of review, a conclusion drawn from display data alone is an inference. Getting the cause right and getting a followable procedure right are different, and the second needs the screens opened.

Check one thing at a time on the QA client

SAP NOTES

Check one thing at a time on the QA client

An example plan. Writes stay on the chosen QA client.

1. 01

   Reproduce

   • Test documents shaped like the production ones
   • A proposal for that vendor only, then the exception list and log
2. 02

   Change one thing

   • One pair differing only in BVTYP, one only in payment method
   • Write down the expectation, then compare it with the proposal
3. 03

   Check the fix

   • On screen, in the order a person will follow
   • Reopen any new residual item in FB03
4. 04

   A person decides the run

   • A payment run posts documents, on QA as well
   • A person also decides on payment media

An example plan, not results from a real system.

Once a script writes, it needs a stop. GetSession below is a helper you write from the listing code above. Write it so that it takes only a session on the chosen system and client, and ends on the spot with WScript.Quit 1 when no matching session exists. Guard checks system and client again at the start of the work and just before save. The Guard below has a hole, covered further down. The system name and client number are fictional.

Const QA_SID = "TST"
Const QA_CLIENT = "400"
Set session = GetSession(QA_SID, QA_CLIENT)

Sub Guard()
  If session.Info.SystemName <> QA_SID _
    Or session.Info.Client <> QA_CLIENT Then
    Err.Raise vbObjectError + 9, "Guard", "not QA"
  End If
End Sub

Lay out the QA checks in this order. What follows is an example plan, not results from a real system.

1. Reproduce the symptom. Create test documents on the QA client shaped like the production ones: BVTYP blank on the three invoices, 0002 on the credit memo only. Run a proposal for that vendor only and see whether the credit memo is grouped alone and left as an exception. The evidence is the proposal list, the exception list and the additional log.

Saving the proposal list or log to a file can bring up an SAP GUI security window. It asks whether a file write is allowed, so the agent does not click it. The script stops there, and a person decides after hearing why.

2. Change one thing at a time. If more than one value is a suspect, separate them. With one document pair differing only in BVTYP and another only in payment method, a new proposal shows whether each value alone splits the group. Writing down the expectation first keeps guesses and observations apart.

3. Check the fix. Whether the candidate fix is a change in FB02 or clearing in F-44, try it on screen in the order a person will follow. If clearing creates a residual item, reopen it in FB03, check its posting key, bank fields and payment block, then run the proposal again.

4. A person decides on the payment run. Even in QA, a payment run posts payment documents and clears the items. The payment run and payment media such as a bank file or printout are a person’s call. The script cancels if the scheduling popup shows an unexpected option.

An error in the condition enters Then

SAP NOTES

An error in the condition enters Then

VBScript And and On Error Resume Next

• The one-line condition

  Type = checkbox And Selected

  • And evaluates both sides
  • Selected is read even when it is not a checkbox

• If after the error

  • If the condition errors, Then runs
  • If Then means continue, the check is passed

• Resume Next in the caller

  • Err.Raise inside Guard goes up to the caller
  • If the caller ignores it, the next line, the save, runs

• The rewritten guard

  • Decide inside the guard and call WScript.Quit
  • Keep session selection as the first line of defence

The code is an illustration, not a record from a real system.

Suppose the condition that checks the payment-run popup is written on one line: walk the popup’s children and stop if one is a checkbox and selected. VBScript And evaluates both sides, so reading Selected on an element that is not a checkbox raises an error. Under On Error Resume Next, an error in an If condition resumes at the next statement, which is the first one inside Then. If Then is Cancel, the script stops for the wrong reason. If Then means continue, the check is passed.

So write the safety check as nested If statements. Instead of “stop when something dangerous is found,” make it an allow-list: stop if anything other than the expected controls is visible.

The Guard above has the same hole. If a write script turns on On Error Resume Next and then calls Guard, Err.Raise inside Guard goes up to the caller and is ignored there. VBScript error handling is per procedure, so the caller’s next line, the save, still runs. The defence left is the first step, where the helper picks the session. When no matching session exists, GetSession ends with WScript.Quit 1, so the script never reaches a save on another system’s session.

Write the guard so that it does not raise but ends the script itself. A failed check then fails closed. The routine below is example code for explanation.

Sub Guard()
  Dim ok : ok = False
  On Error Resume Next
  ok = (session.Info.SystemName = QA_SID _
    And session.Info.Client = QA_CLIENT)
  On Error GoTo 0
  If ok = True Then Exit Sub
  WScript.Quit 1
End Sub

What a person guards, and what to check first when stuck

Person	Agent
SAP logon	Finding the open session, driving screens, captures
Allowing scripting and the notice settings	Checking DisabledByServer and read-only mode
Allowing or refusing at the SAP GUI security window	Explaining why it stopped, then waiting
Deciding to reproduce in QA	Designing the reproduction, test documents, proposals, log summaries
Payment run and payment media	Checking the scheduling popup, cancelling outside the allow-list
Replying to the requester	Cause analysis, draft guide, database cross-check

A person holds only a few of these, but each is hard to undo or carries responsibility. Decide up front, as a person, whether to rebuild the same shape of data in QA and check it. If the agent reports that QA has no data, do not accept it as is; check the logon client first. Masking names and bank accounts in screenshots for the requester is also a person’s check.

Symptom	Check first
Control not found	Open notices or confirmation windows, a changed screen
SE16N shows only some columns	ColumnOrder, default layout
Cell reads take long	Only the needed columns; lists through %pc
Script waits forever	A person clicks the SAP GUI security window
Korean output is garbled	Write a UTF-8 file and read the file
Then runs on a condition error	Nested If, allow-list
Guard does not stop the save	Quit inside the guard; session selection first
QA data seems missing	Logon client and USING CLIENT
Vendor drops out of the proposal	Payment block, payment method and bank details, due date, grouping fields, additional log
Same-day entries drop out of the payment	Entry date CPUDT stamped with the server date

There are four rules. A person logs on. Production is display only. A write script takes only a session on the chosen system and client. Values changed through the GUI are checked again in the database. One more: a safety check is code too, so make it fail on purpose once and see that it stops.

The same frame works for writing business manuals. Running a process in QA and recording its screens and steps has the same shape: a person sets the boundaries, and the agent drives the screens.