SAP Activities

Version: 1.0.5  ·  ID: zoan-packages-sap  ·  Author: Zoan Software

The SAP package automates SAP GUI for Windows, SAP’s desktop client. The bot logs on to the system, runs transactions, fills in fields, presses buttons and reads what SAP shows —fields, status bar, ALV grids, classic lists— just like a person in front of the screen, but without getting tired and at any hour.

Underneath it uses SAP GUI Scripting, SAP’s official automation interface. It does not work with screen coordinates or image recognition: every field and button has an identifier generated by SAP itself (for example wnd[0]/usr/ctxtDATABROWSE-TABLENAME), stable across runs, users and machines.

SAP, desktop or browser?

• For SAP GUI for Windows (the classic SAP Logon), use this package.
• For other Windows applications, use Desktop.
• For SAP or other systems used in the browser (Fiori, portals), use Browser.

Requirements

The robot runs on Windows with SAP GUI for Windows installed. On top of that, scripting must be enabled at both ends:

Where	What to enable
SAP server	The profile parameter sapgui/user_scripting = TRUE (checked and changed with transaction RZ11). Usually done by the Basis team.
SAP GUI client	In SAP GUI: Options → Accessibility & Scripting → Scripting → Enable scripting.

If either one is missing, the activities fail with a message that says so: SAP GUI answers but does not hand over the scripting engine.

Also:

• SAP Logon must be running (saplogon.exe). SAP — Attach also needs a session that is already logged on; SAP — Log on opens the connection by itself, but it does not start the program: launch it first, for example with Open App.
• The robot and SAP GUI run in the same Windows session: scripting only sees the SAP GUI windows of the user the robot runs as.

For unattended runs

On that same SAP GUI options screen, turn off the notifications shown when a script attaches to SAP GUI or opens a connection: they are windows that wait for someone to accept them. And if you are going to export files, check Options → Security: see SAP — Export list.

Concept 1: the session

Every activity works on an SAP session (ZoanSapSession): an SAP GUI window already logged on to the system. There are two ways to get one:

	SAP — Log on	SAP — Attach
What it does	Opens an SAP Logon connection and logs on with a user and password.	Attaches to a session that is already open.
Credentials	The password comes from a Zoan Cloud credential.	Does not touch credentials.
How it chooses	By the SAP Logon entry name (or a /H/server/S/3200 string).	By system (system) and client (client); with neither, the first open session.
When it ends	Closes the connection it opened (unless keepOpen).	Detaches and leaves SAP open as it was.
Best for	Unattended robots that cannot rely on someone leaving SAP open.	Attended flows, or machines where a person or SSO does the logon.

As in Desktop, there are two ways to hand the session to the other activities:

Option A — with body (scope session)

The activities you place inside the body of SAP — Log on or SAP — Attach inherit the session automatically; you don’t set session on any of them.

SAP Attach   system = "DEV"   client = "001"
 └─ body:
      SAP Run Transaction   code = "SE16"
      SAP Get Text   selector = "wnd[0]/titl"   → output: title

Option B — session in a variable

Without body, the activity returns the session as its output. You then pass it in the session parameter of each activity.

SAP Attach   system = "DEV"   client = "001"   → output: sap
SAP Run Transaction   session = sap   code = "SE16"

Concept 2: SAP selectors

The selector of an SAP activity is the element’s scripting id, always relative to the session. It reads left to right, from the window down to the control:

Part	What it is
wnd[0]	The main window. wnd[1], wnd[2]… are modal windows (dialogs) on top.
usr	The screen’s work area (fields, buttons, tables).
tbar[0]	The standard toolbar, which holds the command field (okcd).
tbar[1]	The application toolbar (for example, the Execute button btn[8]).
sbar	The status bar.
mbar	The menu bar.

The prefix of the last segment tells the control type: txt/ctxt (text fields), btn (button), chk (checkbox), rad (radio button), cmb (dropdown), lbl (label), tbl (classic table), shell (ALV, trees). For example, wnd[0]/usr/ctxtDATABROWSE-TABLENAME is the “Table Name” field of transaction SE16.

You can provide the selector in two ways:

• Capture it with the capture button of the Designer’s selector editor, pointing at the element in the SAP GUI window (it works like UI Discover › Desktop mode; the Designer detects that the window belongs to SAP and asks SAP GUI Scripting).
• Type or paste it as text, from wnd[...] onwards. This lets you reuse ids you already have, for example from a recording made with SAP GUI itself.

If you paste an absolute id, with the connection and session prefix (/app/con[0]/ses[0]/wnd[0]/…, as the Scripting Tracker or an SAP GUI recording gives it), the activity strips that prefix and reads the id relative to the robot’s session: connection and session numbers change from one machine to another, and the session was already chosen by SAP — Attach or SAP — Log on. The one exception: if the full prefix points to another session that is open at that moment, the activity fails instead of writing into the wrong session. The Designer also warns you when a selector carries that prefix.

Classic table cells

In a classic table cell id, such as wnd[0]/usr/tblSAPLXYZTC_ITEMS/ctxtITEM-MATNR[1,12], the second number is the visible row (0-based), and how many rows are visible depends on the window size and the screen resolution. From index 5 on (the sixth visible row) the cell may not exist on another machine, and the Designer flags it with a warning. Maximize the window with SAP — Maximize or work with SAP — Read table and SAP — Set cell.

When the element “does not exist”

If a selector is not found, the error tells you which screen the session is on (program, dynpro number and transaction). In SAP, a “not found” almost always means the flow is on a different screen than you expected, not that the selector is wrong.

Concept 3: waiting

The activities already wait on their own, at two levels:

1. SAP busy. Before and after each action, they wait for SAP to finish processing (up to 60 seconds). You don’t need to add pauses after pressing Enter or a button.
2. The element. Activities that look up an element by selector look for it every 200 ms until it appears: up to elementTimeout seconds, set once on SAP — Log on or SAP — Attach and carried by the session. If you don’t set it, the timeout from the project settings applies and, if the project doesn’t define one either, 30 seconds. Each of those activities also has its own timeout parameter (in seconds, decimals allowed) that overrides the scope’s value.

If SAP is still busy after 60 seconds, the activity fails with The SAP session is still busy after 60000 ms.

With elementTimeout = 0 (or timeout = 0) the activity fails on the first try, which is what you want while debugging a selector.

Two exceptions

• SAP — Element exists does not wait for the element to appear: it only waits for SAP to finish processing and checks once. To wait for something to appear without acting on it, use SAP — Wait for element.
• The timeout of SAP — Attach is something else: how long to wait for the session to show up, and it defaults to 0 (a single attempt).

Concept 4: the status bar

SAP reports almost everything through the status bar: errors, warnings and confirmations. Activities that trigger actions (SAP — Press button, SAP — Press toolbar button, SAP — Send key, SAP — ALV toolbar, SAP — Run transaction, among others) read it after acting:

• Messages of type E (error) or A (abort): the activity fails with SAP’s text.
• Any other type (S, W, I): it is written to the log and the flow goes on.

Careful: SAP announces important things with type S (success), such as “No table entries found for specified key”. If your flow depends on that, read it with SAP — Read status bar and decide with an If.

Fixed ids the activities use

Some activities work on standard SAP GUI controls whose id is always the same. Knowing them helps you understand an error or drive a similar dialog by hand:

Id	What it is	Used by
wnd[0]/tbar[0]/okcd	Command field	SAP — Run transaction, SAP — Export list (%pc)
wnd[0]/sbar	Status bar	Every activity that reads the status bar
wnd[0]/mbar	Menu bar	SAP — Select menu with path
wnd[0]/usr/txtRSYST-MANDT · txtRSYST-BNAME · pwdRSYST-BCODE · txtRSYST-LANGU	Client, user, password and language on the logon screen	SAP — Log on
wnd[1]/usr/radMULTI_LOGON_OPT1 … OPT3	Options of the multiple logon dialog	SAP — Log on
wnd[1]/usr/ctxtDY_PATH · ctxtDY_FILENAME · ctxtDY_FILE_ENCODING	Folder, name and encoding in the “Save File” dialog	SAP — Save file dialog and the export activities
wnd[1]/tbar[0]/btn[0] · btn[11]	Generate and Replace buttons of the “Save File” dialog	SAP — Save file dialog

Errors common to all activities

These messages can come up in any activity that works on a session. The texts are the ones a robot set to English shows; a robot set to Spanish shows them in Spanish. To handle them, wrap the stretch in a Try / Catch (and leave evidence with SAP — Screenshot in the catch) or retry with Retry.

Message	Cause and fix
No SAP session. Wrap the activities in a sap-attach, or pass one to the 'session' parameter.	The activity is outside the body of SAP — Attach or SAP — Log on and got no session. Move it into the body or pass it the session.
Component '…' does not exist in the SAP session. Waited … s for it to appear. The current screen is … dynpro … (transaction …). Check that the transaction reached the screen you expected.	The selector did not appear in time. Look at the program, dynpro and transaction in the message: almost always the session is on another screen (a dialog in front, a step that didn’t happen).
'selector' is required.	The selector arrived empty.
The selector points to another open SAP session (…), not the robot's (…). Remove the '/app/con[..]/ses[..]' prefix to use the robot's session, or attach to that session.	The id carries an /app/con[N]/ses[M] prefix of another open session. Remove the prefix.
The SAP session is still busy after 60000 ms. The server has not returned control.	SAP did not finish processing within a minute (a very heavy report, a server lock). Narrow the selection or retry later.
SAP replied [E …]: …	After the action, the status bar showed a message of type E or A. The text is SAP’s; fix the data or the screen and try again.
'…' must be true or false; got '…'.	A boolean parameter received an expression that is neither true nor false.

Record instead of build

The Designer’s Record button also records in SAP GUI. While recording, work in SAP as usual: each action becomes an activity inside an SAP — Attach set to the system and client of the session you worked in. It records transactions (SAP — Run transaction), typing into fields (SAP — Set text), buttons (SAP — Press button), checkboxes (SAP — Set checkbox), radio buttons (SAP — Select radio), tabs (SAP — Select tab), dropdowns (SAP — Select from dropdown) and function keys (SAP — Send key), including F keys with Shift or Ctrl and shortcuts such as Ctrl+F or Ctrl+S.

Passwords are not recorded: the Designer warns you so you can fill that step with a credential. And since the recording starts with SAP — Attach, if the robot will run unattended it is usually worth replacing it with an SAP — Log on afterwards.

Modal windows

Many SAP screens open modal windows on top of the main one (wnd[1]): confirmations, warnings, system messages. While one is open, the main window does not respond; for example, SAP — Run transaction cannot find the command field.

SAP — Log on handles the multiple logon dialog on its own and stops if SAP requires a password change. Any other dialog, such as the system messages after logon, is left open and reported in the log, so nothing gets accepted without being read. Close it with SAP — Close modal.

Activities

Session and navigation

Activity	Type	Output	What it does
SAP — Log on	sap-logon	ZoanSapSession	Opens an SAP Logon connection and logs on
SAP — Attach	sap-attach	ZoanSapSession	Attaches to an open session
SAP — Run transaction	sap-run-transaction	—	Runs a transaction by code and checks that it opened
SAP — Send key	sap-send-key	—	Sends a function key (Enter, F3, F8…)
SAP — Select menu	sap-select-menu	—	Selects a menu bar entry
SAP — Select tab	sap-select-tab	—	Switches tabs
SAP — Close modal	sap-close-modal	boolean	Closes a modal window, if there is one
SAP — Maximize	sap-maximize	—	Maximizes the SAP window

Interact

Activity	Type	Output	What it does
SAP — Set text	sap-set-text	—	Types a value into a field
SAP — Press button	sap-press-button	—	Presses a button on the screen
SAP — Press toolbar button	sap-press-toolbar-button	—	Presses a button on the standard or application toolbar
SAP — Set checkbox	sap-set-checkbox	—	Checks or unchecks a checkbox
SAP — Select radio	sap-select-radio	—	Selects a radio button
SAP — Select from dropdown	sap-select-combo	—	Selects a dropdown entry, by key

Read and wait

Activity	Type	Output	What it does
SAP — Get text	sap-get-text	string	Reads the text of a field or label
SAP — Element exists	sap-element-exists	boolean	Does the element exist on the current screen?
SAP — Wait for element	sap-wait-for-element	—	Waits until an element exists on the screen
SAP — Read status bar	sap-read-status-bar	Dictionary<string,object>	Type and text of the status bar message
SAP — Screenshot	sap-screenshot	string	Saves an image of the SAP window

Tables, lists and trees

Activity	Type	Output	What it does
SAP — Read table	sap-read-table	List<Dictionary<string,object>>	Reads an ALV grid or classic table into a list of rows
SAP — Set cell	sap-set-cell	—	Writes a value into a cell
SAP — Select rows	sap-select-row	—	Selects rows in an ALV grid
SAP — ALV toolbar	sap-grid-toolbar	List<string>	Presses an ALV toolbar button, or lists the available ones
SAP — Read classic list	sap-read-list	List<Dictionary<string,object>>	Reads a classic report list as rows of text
SAP — Expand tree node	sap-tree-expand	—	Expands a tree node
SAP — Select tree node	sap-tree-select	—	Selects a tree node
SAP — Read tree	sap-tree-read	List<Dictionary<string,object>>	Reads the nodes of a tree

Export

Activity	Type	Output	What it does
SAP — Export list	sap-export-list	string	Exports the screen’s classic list to a file
SAP — Export ALV grid	sap-grid-export	boolean	Triggers an ALV grid’s export
SAP — Save file dialog	sap-save-file-dialog	string	Fills in and confirms SAP’s “Save File” dialog

A typical flow

Log on, close the system message if it shows up, look up table T000 in SE16 and export it:

SAP Logon   connection = "DEVELOP"   client = "001"
            user = credential("sap-dev")["user"]   password = credential("sap-dev")
 └─ body:
      SAP Close Modal
      SAP Run Transaction   code = "SE16"
      SAP Set Text   selector = "wnd[0]/usr/ctxtDATABROWSE-TABLENAME"   value = "T000"
      SAP Send Key   key = Enter
      SAP Press Toolbar Button   selector = "wnd[0]/tbar[1]/btn[8]"
      SAP Export List   path = "C:\output\"   fileName = "t000.txt"   → output: file

Next steps

• SAP — Log on and SAP — Attach — the starting point.
• SAP — Run transaction — navigate by transaction code.
• SAP — Read table and SAP — Export list — get data out of SAP.