SAP Module

Prerequisites

To be able to use the Appian RPA SAP module, SAP GUI Scripting have to be enabled, so we must bear in mind that the following requirements have to be met by the machine where the Appian RPA Agent is running, i.e., the Appian RPA resource.

Java JRE

The Appian RPA agent running on resources is developed in Java, so it needs a Java Runtime Environment (JRE) to be executed. SAP GUI Scripting can be used with a 64-bit JRE if you have the SAP GUI 750 version (or newer). If the SAP GUI version is less than 750, the Appian RPA agent will need to use a 32-bit JRE. We have two different alternatives to achieve this:

  1. Set the default JRE on the resource to be 32 bits:
    • By installing only the 32-bit version.
    • By setting the default JRE the 32-bit one, just configuring the JAVA_HOME and PATH environment variables.
  2. Generate the Appian RPA agent to use a JRE located on a specific directory.
    • To do so, a Appian RPA platform administrator must generate the resource for us using a specific configuration to indicate the folder where the 32-bit JRE files are.

Run agent with administrator privileges (once)

The first time you run the SAP module, you will perform some configuration tasks that require to write or to modify some values in the Windows registry. The changes are as follows:

  • Enable 64-bit JRE (if required)
  • Enable SAP GUI Scripting on the client
  • Uncheck the SAP GUI option so that it does not request permission to control the sap session using a remote script.

Execution with administrator privileges will only be necessary the first time a robot is executed with this module. Once the modifications have been made, it can be used with the restricted permissions.

Using a DLL as a bridge between Java and SAP GUI Scripting

For the Appian RPA module for SAP to work, you need the file jacob-1.18-x86.dll or jacob-1.18-x64.dll in the same directory as the Appian RPA agent executable (jidoka.exe). This file is directly copied by the Appian RPA agent to the corresponding directory the first time the module is used in the resource.

The first time you run a robot with the SAP module and copy the corresponding DLL, you must restart the Appian RPA agent since this file is loaded when you start it.

Enable SAP GUI Scripting in SAP

To control SAP using SAP GUI Scripting, we have to enable this feature in our environment. This activation must be done both on the server and the client side.

Enable SAP GUI Scripting on the server

  1. Open the RZ11 transaction.
  2. In the Mantain Profile Parameters window, select "sapgui/user_scripting".
  3. Click Display.
  4. In the Metadata for Parameter sapgui/user_scripting", click Change Value.
  5. Fill in the New Value field with "TRUE".
  6. Click on the Save Change icon (or press Ctrl+S).

If SAP GUI Scripting is not active on the server, initializing the SAP module on the platform will throw a SapFatalException.

Enable SAP GUI Scripting on the client

This step is no longer required once you have run the Appian RPA agent with administrator privileges. We keep the information to show which values are modified by the agent.

  1. On the main page, click on Customize Local Layout (or press Alt+F12), then select Options…
  2. Click on Accessibility & Scripting, then select Scripting on the tree located on the left-hand menu.
  3. In this window, the option Enable scripting must be selected, leaving the rest unselected.
  4. Click OK.

SAP Module Initialization

Before starting to work with the SAP Appian RPA module, it is necessary to initialize their components following a specific order.

The first step to use this module in a robot is to include its Maven dependency in the pom.xml file, as we've already done for other modules.

1
2
3
4
5
<dependency>
    <groupId>com.novayre.jidoka.module</groupId>
    <artifactId>jidoka-sap-api</artifactId>
    <version>${jidoka.version}</version>
</dependency>

Once the dependency is added, we can access all objects required to work with SAP GUI Scripting from the Appian RPA API.

To start, we must open the SAP GUI application and login to the system we want to automate. Due to security purposes, SAP GUI Scripting can't control this first window, so we have to handle how to open SAP GUI and select the target system using other methods in the Appian RPA API.

2235709.png

The code bellow shows a complete SAP initialization example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
  
    /** The Appian RPA SAP module. */
    private IGuiApplication sap;

    /**
     * Sap open action.
     *
     * @throws JidokaException the jidoka exception
     */
    public void sapOpen() throws JidokaException {
        
        Path sapPath = Paths.get(SapConstants.App.SAP_EXECUTABLE_PATH, SapConstants.App.SAP_EXECUTABLE);

        // open SAP logon window
        ProcessBuilder pb = new ProcessBuilder(sapPath.toString());

        try {

            pb.start();
            // Wait for the initial window title (For example 'SAP Logon 750')
            waitFor.window(30, true, true, SapConstants.Titles.SAP_LOGON_WINDOW_TITLE);

            server.info("SAP application opened");

            // Type the SAP connection name and press the key "Enter". In this example we use 'SAP Demo'
            keyboard.type(SAP_CONNECTION).pause(1000).enter();
            waitFor.window(SapConstants.Timeouts.MEDIUM_WAIT, true, SapConstants.Titles.SAP_LOGON_WINDOW_TITLE_FIRST);
            server.info("Connected to: " + SAP_CONNECTION);

            // Instantiate the SAP module if it wasn't done before
            if (sap == null) {
                sap = ISap.getInstance(this);
            }

            // Appian RPA SAP Module initialization
            if (!sap.isInitialized()) {
                sap.init();
            }

            GuiMainWindow win = (GuiMainWindow) sap.getCurrentSession().getActiveWindow();

            win.iconify();
            win.maximize();

            windows.pause(2000);

            server.info("Initializing Appian RPA SAP module");

        } catch (IOException | JidokaUnsatisfiedConditionException e) {
            throw new JidokaException("SAP could not be opened: " + e.getMessage(), e);
        }
    }

Let's explain this method step by step.

Open SAP GUI

The robot will use the ProcessBuilder object of the Appian RPA JDK to start a Windows process, using the executable file defined in the SapConstants.App.SAP_EXECUTABLE constant. The installation path by default in Windows 7 is something like "C:\Program Files (x86)\SAP\FrontEnd\SAPgui\saplogon.exe".

This method waits for 30 seconds until a window with the title defined by the SapConstants.Titles.SAP_LOGON_WINDOW_TITLE constant appears. In this case, it's "SAP Logon 750", but it could also be a regular expression, for instance: "SAP.*".

Select an entry to SAP

At this point, we must select the entry to the SAP system we need. Usually, the window has the focus in the connections list, so we will type the text of the system entry we want to access to. This example types the text defined in the constant SAP_CONNECTION ("SAP Demo"). This will select the system to access. Once the text is typed, the robot will send the "Enter" keystroke.

1
2
3
4
keyboard.type(SAP_CONNECTION).pause(1000).enter();
waitFor.window(SapConstants.Timeouts.MEDIUM_WAIT, true,
    SapConstants.Titles.SAP_LOGON_WINDOW_TITLE_FIRST);
server.info("Connected to: " + SAP_CONNECTION);

The next line of code will wait for the SAP GUI login window to appear.

2235710.png

Initialize the Appian RPA SAP module

Once we're in the login window, the SAP module can start to manage the application. To connect our SAP module instance to the application just opened, we'll execute the following code snippet:

1
2
3
4
5
6
7
8
9
          // Instantiate the sap module if we haven't done before
            if (sap == null) {
                sap = ISap.getInstance(this);

            }
            // Appian RPA SAP Module initialization
            if (!sap.isInitialized()) {
                sap.init();
            }

The lines of code below are optional. They are used to maximize the window and send to the log execution trace a message indicating that the module has been initialized and it's ready to be used.

1
2
3
4
5
          GuiMainWindow win = (GuiMainWindow) sap.getCurrentSession().getActiveWindow();
            win.iconify();
            win.maximize();
            windows.pause(2000);
            server.info("Initializing Appian RPA SAP module");

Use of SAP GUI scripting

At this point, we must have initialized the SAP module.

In the following points of the documentation, we'll talk about how to use the main components of SAP GUI Scripting.

It's important to know the Tracker tool. This tool is used to inspect the elements displayed on a SAP window. Using this tool, we'll be able to know the type of the element and its unique identifier to locate them by using the methods in the API and interact with them.

You can check the SAP application help from the SAP GUI Scripting Help inside the Customize Local Layout option of the tool bar.

SAP GUI component hierarchy

The graphic below shows how the components are organized in SAP GUI, so we can handle the binding between the module and the SAP application to automate.

2235419.png

GuiApplication

GuiApplication represents the process in which activities inside SAP occur. It has to be only one GuiApplication object instantiated. The method ISap.getInstance(IRobot robot) is in charge of this, since this class uses the Singleton pattern to be instantiated.

GuiConnection

An instance of GuiApplication accepts one or more connections from a GuiConnection to the SAP systems available for scripting. Although we can control more than one, the common case is to have only one.

GuiSession

Each instance of GuiSession corresponds to a new Session in SAP. Each window opened inside the same connection is a new instance of GuiSession.

For instance, in a resource where three SAP transactions were opened, you can check that three sessions are available by using the SAP element inspector: Tracker.

SAP window component hierarchy

An instance of GuiSession contains, at least, one instance of GuiMainWindow. This instance is the entry point to the interaction of the Appian RPA robot with the SAP GUI windows.

The element hierarchy inside a GuiMainWindow is as follows:

2235420.png

Each of these elements has its own representation as a class of the API of the Appian RPA SAP module. You can find more details in the next section.

Accessing components in windows

Main components in a SAP window

The main element from which we can interact with the components in SAP windows is GuiMainWindow. This object gives us access to each of the elements that make up a SAP window:

  • The menu (GuiMenuBar)
  • The tool bars (GuiToolBar)
  • The user area (GuiUserArea)
  • The status bar (GuiStatusBar)

2235435.png

We can get instances of these objects directly from the methods provided by the GuiMainWindow class.

1
2
3
4
5
6
7
8
IGuiSession guiSession = sap.getConnection().getOpenSessions().get(0);
 
GuiMainWindow activeWindow = (GuiMainWindow) guiSession.getActiveWindow();
 
GuiMenuBar menuBar = activeWindow.getMenuBar();
GuiToolBar toolBar = activeWindow.getToolBar();
GuiUserArea userArea = activeWindow.getUserArea();
GuiStatusBar statusBar = activeWindow.getStatusBar();

In the next points, we'll show some examples of how to get access to several types of elements which can be used as a reference to build a Appian RPA robot that automates an SAP process.

The findById(…) method

The common method to locate an element inside an SAP window is findById. This method is available in the GuiVContainer class, from which all elements containing other elements extend.

This method allows us to get an instance of a component by its id, that can be obtained by using the Tracker element inspector.

The findById(…) method returns an instance of GuiComponent. All the elements of an SAP window of the user interface extend this class, hence we can get the instance of the component extending GuiComponent.

The basic example: Text fields

We are going to see a basic example of how to obtain a text field and read or set its content. To do so, we'll use the login window of an SAP installation.

Using the Tracker tool, we can get the identifier and the type of the component.

In this case, the identifier is "RSYST-BNAME" (relative to the user area) and the type of the component is GuiTextField. The following code snippet shows how to set the value on the user field:

1
2
3
4
5
6
7
8
9
IGuiSession guiSession = sap.getConnection().getOpenSessions().get(0);
 
GuiMainWindow activeWindow = (GuiMainWindow) guiSession.getActiveWindow();
 
// Login field
GuiTextField user = activeWindow.getUserArea().findById("RSYST-BNAME");
 
user.setFocus();
user.setText(sapCredentials.getUsername());

Press a button in the tool bar

This time, we're going to press a button in the tool bar. Again, dealing with the login window, we'll press the Enter button.

2235442.png

Using the Tracker again, we get both the id and the type.

2235443.png

In the following code snippet, we can see how to obtain the GuiButton component and invoke its press() method:

1
2
3
4
IGuiSession guiSession = sap.getConnection().getOpenSessions().get(0);
GuiMainWindow activeWindow = (GuiMainWindow) guiSession.getActiveWindow();
GuiButton btn = activeWindow.getToolBar().findById("btn[0]");
btn.press();

Tracker

To be able to interact with the elements of SAP window, we must know both the type of the element (a text field, a button, a tool bar, etc.) and its unique identifier.

This information can be obtained using the Tracker tool. This tool is, among others, an inspector of SAP GUI elements. You can download Tracker from its official website.

Open Tracker

Once we are on a SAP window, by executing Tracker a window will show up from which you can navigate through the component tree of the active SAP session. To see the available windows, we must click on the Scan scripting objects of all sessions button () or send the key sequence Alt+S.

Each first-level line of the component tree has its SAP window. If we have only one opened but we access to a second one (for instance a pop-up window), we can check that, after reloading, two lines will appear.

For instance, in the following image we can see a SAP window with an open transaction (PA20) in which we've accessed to the Restrict Value Range pop-up window.

2235454.png

By using Tracker to see the component tree, we can observe that it shows two first-level lines in the tree. The first one refers to the main window, while the second one is the pop-up window.

2235455.png

2235456.png

In the screenshots above we see that, even they are two windows, their type is different. One is of type GuiMainWindow and the other is of type GuiModalWindow. Both types of windows have their own representation in the Appian RPA API, although these two objects extend the GuiFrameWindow in the end, which provides the necessary methods to access to their components.

Component tree

After opening the first level of the component tree, we see a division of the areas of a SAP window:

2235465.png

It provides access to the following elements:

  • mbar: Menu bar, represented in the API as the GuiMenuBar class.
  • tbar[0] / tbar[1]: Tool bar, represented in the API as the GuiToolBar class. In this case we see that there are two elements "tbar", with indices [0] and [1] in the name. This means that more than one element can be present at this level, i.e., an SAP window can contain more than one tool bar.
  • usr: It's the user area. Here we'll find the main elements of the window (text fields, buttons, labels, tables, etc.). It's represented in the API as the GuiUserArea class.
  • sbar: Status bar. It's represented in the API as the GuiStatusBar class. These elements have been detailed to be used as starting points to locate their components from the API in a Appian RPA robot. We are going to show an example of how to use the information provided by Tracker in a robot.

Using the information of Tracker in the API

In the Tracker window we can get the values ID and Type. These are the required data to reference an object. Let's see an example.

We use as reference the following SAP window and its associated view in Tracker. Here, we select the tree element corresponding to the second tab in the SAP window, "Empl. contract data", so we can extract the information required to select the tab using the Appian RPA SAP module API.

2235457.png

2235458.png

We can see the following information:

  • ID: "/app/con[0]/ses[0]/wnd[0]/usr/tabsMENU_TABSTRIP/tabpTAB02".
  • Text: "Empl. contract data".
  • Type: GuiTab.

Now we'll work with the API. The starting point is always an object of type GuiMainWindow or GuiModalWindow. Let's see the following code snippet:

1
2
3
4
5
GuiFrameWindow activeWindow = sap.getCurrentSession().getActiveWindow();
 
GuiUserArea userArea = activeWindow.getUserArea();
GuiTab tab2 = userArea.findById("tabsMENU_TABSTRIP/tabpTAB02");
tab2.select();

As you can see, both in the Tracker component tree and in its ID ("/app/con[0]/ses[0]/wnd[0]/usr/tabsMENU_TABSTRIP/tabpTAB02"), the tab is located inside the user area. Therefore, we must obtain the GuiUserArea instance of the active window first.

Then, we use the findById(…) method of the GuiUserArea instance to locate the element. The unique ID provided by Tracker is an absolute path, but we only need the relative path to the object we're using to locate the element.

  • Absolute path: "/app/con[0]/ses[0]/wnd[0]/usr/tabsMENU_TABSTRIP/tabpTAB02".
  • Relative path to the user area: "tabsMENU_TABSTRIP/tabpTAB02".

The findById(…) method returns a GuiComponent instance. All the elements of an SAP window of the user interface extend this class, so we can use directly the GuiTab instance.

This is the way we use Tracker to locate the elements of an SAP windows. This tool contains also other features as record of scripts, etc. All this information can be checked at its reference page.

SAP example robotic process

We're creating an example robot using the SAP module. To do so, we'll use an already developed Eclipse project. The goal is to demonstrate how to use several components of SAP GUI Scripting from the Appian RPA API.

To make this robot work, it is required an installation of SAP IDES having available the transaction to use: S_PH9_46000223 (Entries and leavings).

You can download the complete source code of this example, along with the required support files, in the links below:

Description Link
Source Code robot-developmentguide-sap.zip
Jacob v.1.18 win64 library jacob-1.18-x64.dll

Environment configuration

  • Development:
    • IDE: Eclipse
    • JDK 1.8
    • Maven 3
    • Appian RPA Modules:
      • Client
      • SAP
  • Resource:
    • OS: Windows
    • JRE 1.8
    • Applications:
      • SAP IDES (In English)

Eclipse Project

You must import the Eclipse project included in the zip file attached in the SAP example robotic process section of this tutorial. After importing the project, it is very important to modify the pom.xml file. You have to fill in the tag <parent> with the Appian RPA version you are using, and change the tag <profiles> with the configuration of your Maven repository.

Workflow

The robot will open the SAP application and perform each of the following actions:

  • Open a connection called "SAP Demo".
  • Log in with the user configured in the credential vault of the Appian RPA Console.
  • Open the transaction S_PH9_46000223.
  • Search an employee with the date range received by parameter.
  • Show the identification number of each employee in the execution trace.

modules-sap-workflow.png

You can import this workflow using this file. To import the workflow, you have to click on the import button (2235477.png), and paste the data included in the file.

Support Files

The robot needs the jacob-1.18-x86.dll library, which must be located in the same directory where the Appian RPA Agent (jidoka.exe) is located. The library is available in the Prerequisites section of the SAP module documentation.

2235479.png

The robot requires a date range provided through the instructions DATE_FROM and DATE_TO.

modules-sap-instructions.png

Execution

Before executing this robot we must check that we have the necessary environment for the robot to work. Also, the resource must comply with the Prerequisites indicated in the module documentation.

SAP GUI installation path

The robot assumes that the SAP GUI installation path is the one selected by default in a Windows 7 installation. The path to the directory and the name of the executable file are defined in the SapConstants.java class:

1
2
3
4
5
6
7
8
9
/**
 * App Paths.
 */
public class App {
     
    public static final String SAP_EXECUTABLE_PATH = "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui";
    public static final String SAP_EXECUTABLE = "saplogon.exe";
     
}

SAP Credentials

The robot uses the credentials configured in the Appian RPA Console. In the class SapRobot.java we can check the name of the application it uses in the credentials vault.

1
2
/** SAP credentials parameter. */
private static final String CREDENTIALS_SAP_APPLICATION = "SAP_IDES";

In the console we must have a credential configured with a valid user for our installation. We must also assign the necessary permission, which must also have configured the robot.

modules-sap-credentials.png

Entry to the system

The entry to the SAP system used by the robot is "SAP Demo", which is configured in the following constant of the SapRobot.java class:

1
2
/** SAP connection name. */
public static final String SAP_CONNECTION = "SAP Demo";

2235869.png

Open in Github Built: Fri, Nov 12, 2021 (02:39:09 PM)

On This Page

FEEDBACK