SAP automation

The sap command drives the SAP GUI for Windows through SAP GUI Scripting: it signs in, starts transactions, fills fields, presses buttons and reads tables and messages, by the components' ids. It is much more reliable than clicking SAP screens by picture or position.

#Before you start

SAP GUI Scripting must be allowed in two places:

1. On the SAP system (your SAP Basis team): profile parameter sapgui/user_scripting = TRUE (transaction RZ11). For users of a dedicated robot account this is often enabled for that account only.
2. On the agent machine: SAP GUI options → Accessibility & Scripting → Scripting → Enable scripting; turn off Notify when a script attaches to SAP GUI and Notify when a script opens a connection, or a pop-up waits for someone to click it.

The agent machine needs the SAP GUI for Windows (SAP Logon) installed. Botream ships no SAP component.

#A first task

set --name:sapUser --type:credential --vault:"SAP" --credential:"RPA_USER"
sap --action:logon --connection:"PRD - Production" --client:100 --credential:$sapUser$ --language:EN
sap --action:starttransaction --transaction:VA03
sap --action:settext --id:wnd[0]/usr/ctxtVBAK-VBELN --value:$orderNo$
sap --action:sendkey --key:Enter
sap --action:getstatusbar --failonerror:true --output:status
sap --action:gettext --id:wnd[0]/usr/subSUBSCREEN_HEADER:SAPMV45A:4021/txtVBKD-BSTKD --output:poNumber
sap --action:logoff

• logon starts SAP Logon when it is not running, opens the connection by its description as SAP Logon lists it, and signs in with the client, the user and password of a credential and the language. When the user is already signed in elsewhere, --multiplelogon decides: continue (default), endothers or fail.
• attach uses a session that is already open (signed in by hand or by single sign-on): the first connection, or the one whose description matches --connection (wildcards: PRD*), and its first window or --sessionindex.
• Every other action works in the session named by --session (SAP by default), so a task can work in two systems at once.
• A session opened by logon is signed off when the run ends, also after an error. An attached session stays open.

#Component ids

Components are addressed by their scripting id, such as wnd[0]/usr/ctxtVBAK-AUART (main window, user area, a text field with a value help) or wnd[0]/tbar[1]/btn[8] (the Execute button). Get them:

• in the editor: Capture next to Id dims the screen; click the field, button or table in the SAP window and its id is filled in;
• or with SAP's own script recorder (SAP GUI → Customize Local Layout → Script Recording and Playback): record what you do and copy the ids from the script. Ids that start with /app/con[0]/ses[0]/ are fine; the session part is dropped.

Pop-ups are wnd[1], wnd[2]… Use exists before acting on one that may not appear.

#Actions

#Reading a report

sap --action:starttransaction --transaction:VA05
sap --action:settext --id:wnd[0]/usr/ctxtVBCOM-KUNDE --value:$customer$
sap --action:press --id:wnd[0]/tbar[1]/btn[8]
sap --action:gettable --id:wnd[0]/usr/cntlGRID1/shellcont/shell --output:orders
loop --type:datatable --table:$orders$ --variable:row
    log --message:"$row.Sales Document$: $row.Net Value$"
endloop

Column titles become the data table's column names; a title that appears twice gets a number (Date 2).

#Good practice

• Use a dedicated SAP user for the robot, with the roles it needs and a password kept in a vault.
• Check the status bar after saving (getstatusbar --failonerror:true) and handle errors in a catch.
• Keep the SAP GUI window size and theme fixed on the agent machine; ids do not change with them, but table controls show as many rows as fit.
• When a screen differs between users (variants, personal settings), set them for the robot user once by hand.