Notes on installing SAPGUI for Java for macOS


Intro

These notes might help people with the eponymous task; they are not as wide-ranging and thorough as the official instructions and guides from SAP, instead these are just some remarks based on author’s recent experience, which might be helpful 👌 (or might not 😱 ).

This blog assumes you have local admin rights to your MacBook, and the ability to use Terminal. Also we assume that you have access to SAPGUI for Java version 7.70 or later (the freeware version 7.50 from e.g. SAP NetWeaver Developer Edition, has a different installation procedure (requires separate OpenJFX 11 library), and anyway the version 7.50 is well out of date at time of writing, March 2022); similarly, if you need SAP Secure Login Client, we assume you can get hold of that software.

Installing the SAPGUI for Java for MacBook software

To run the jar file which then installs the SAPGUI client on your MacBook, you will need a suitable Java SDK (a.k.a. JDK). (Note that you only need this JDK for installing – the SAPGUI client contains its own “internal” JVM that it runs on itself). Get the most suitable one free from SAP themselves: the JDK you need is available here – no registration required, just download the stuff you need:

https://sap.github.io/SapMachine/

Choose a latest stable version, choose JDK, choose the right kind of processor (for M1 Macs, that is “macOS aarch64”; for Intel Macs you would choose “macOS x64”), then take the latest minor version of the stable version. In March 2022 when this was written, the choices for an M1 Mac look like so:

Then download it. A dmg file is downloaded. Double-click on it, you should get a Finder window with the main folder shown. Now you can move those files into somewhere that makes sense on your computer, I made a folder under home drive called “SAPGUIforJava” and then created subdirectories “opt” and “jdk” and put the sapmachine-jdk folder there.

Next, it will be convenient to tell our computer the value of the JAVA_HOME environment variable, and to add the java binary directory to the main PATH environment variable, every time we login. (If you have already your own JVM and JDK preferences, then relax, this is only a temporary change that can be removed after installing SAPGUI client). We can do that as follows…

Open Terminal application. It should open by default to your home directory. To check the directory you are in, you can use:

pwd

To move to your home directory, you can use the “cd” command with no options, that returns you from wherever you are in the directory tree to your home directory:

cd

Check if the file called “.zshrc” exists:

ls -al

If it doesn’t yet exist, create it:

touch .zshrc

Once it is existing, we edit the file by adding two lines. So first open the file:

open .zshrc

Then add the paths that match to your locations of jdk “Home” and JDK “bin” folders, like so:

export JAVA_HOME=/Users/myhomedir/SAPGUIforJava/opt/jdk/sapmachine-jdk-17.0.2.jdk/Contents/Home

export PATH=”/Users/myhomedir/SAPGUIforJava/opt/jdk/sapmachine-jdk-17.0.2.jdk/Contents/Home/bin:$PATH”

Save and close. Now you need to logout and login again, so that the info in this file is picked up.

Then you can open a Terminal again, and check that the following commands work fine:

java -version

javac -version

You should get similar results.

Next, we need to get hold of the JAR archive from SAP, for installing the SAPGUI for Java for macOS client on your MacBook.

Now there are two main ways to do this. The first way, if you have an SAP S-User with the appropriate permissions for downloading SAP software, is described below. The second way is if you do not have such S-user with special powers – in that case, if you work in the same organisation as someone with such an S-user, they may be able to provide you with the needed JAR archive.

So to get the software, go to: https://launchpad.support.sap.com/ and click on the “Software Downloads” tile, which takes you here: https://launchpad.support.sap.com/#/softwarecenter

Now, this is not the most intuitive software repository ever, so the author can say it took a couple of hours to find the needed software; here is a good way… In the Search box enter the text “PlatinGUI770” and hit <Enter>. (In March 2022 7.70 was the latest version, you may want to search the SAP Help to check what is the latest version when you come to do this installation and adjust your search term accordingly). From the list, scroll down to get the highest version that is suitable for Mac OS, e.g. at the time of writing the version “4”:

Easiest way to download (no SAP Download Basket installation required) is to click on the I-Ching like icon and go to Content Info, and from there hit the Download icon:

Then (if you want) you can put the downloaded jar for safekeeping in some folder, or you can leave it in the Downloads folder. Anyway, open a Terminal, and using the “cd” command move to the directory the jar is in, e.g. since I put the jar in “SAPGUIforJava” then the command could be:

cd /Users/myhomedir/SAPGUIforJava

Then execute the jar… if your jar is called PlatinGUI770_4-70004682.JAR then:

java -jar PlatinGUI770_4-70004682.JAR

The GUI-Installer starts up…

Go through the steps and hope it installs ok. Here is what success looks like:

You can now open it like any app in Applications (from Launchpad -> SAP Clients, or Spotlight, or Applications directory)… although it will look a bit empty…

…so, from MacBook upper menu (or from Dock-icon menu via Secondary Click) you can Quit SAPGUI (since we have other stuff to do still, and then you would need to restart SAPGUI later in any case). By the way, menu-based Quit is the correct way to close SAPGUI; it doesn’t close properly if you just close the window, and then you are left wondering how to get the window back – spoiler: you cannot, until you really Quit… so remember kids, just use the menu-based Quit and make your own life easier .

If you like, you can open .zshrc file again and either comment out (using the ‘#’-character as the first character of a line) or delete the lines setting JAVA_HOME and PATH environment variables. Your SAPGUI client doesn’t use these any longer, as it has its own JVM instead. (In the past, the SAPGUI for Java clients relied on the local machine’s default JVM, which caused problems, especially for developers, or for everyone in case the corporate policy determined a non-compatible to SAPGUI for Java JVM… so this “internally packaged JVM” solution that arrived maybe in the late 2010s, is rather neat and useful).

Now there are two main ways to proceed here, which have their own advantages and disadvantages, so you can choose how you like from The Server Option or from The Local Option.

The Server Option

The Server Option means using Finder (or Terminal) to connect to the server on which the organisation’s SAPUI xml files are stored, and then specifying in the SAPGUI for Java app which server file you want to use, where the file is typically either accessible via NFS (from a Unix or Linux server), or if the file is on a Windows server then access is via the mounted directory in /Volumes of your local machine. (Below we will consider the case of a Windows server, as this is a rather common setup in organisations, including most of those the author has worked for in the last twenty years. If your organisation uses NFS, then you should be able to scour the internet for good advice about connecting using the “nfs://…” prefix, and then you can test how that plays out when specifying a file in Preferences of SAPGUI).

The advantage of The Server Option is that you are doing what the majority of SAP users do – using the remote “One Source of Current Truth” file maintained on the organisation’s network-servers; this way, you should always have an up to date set of SAP connection items in your SAPGUI client.

A main disadvantage for MacBook users is that you will often or always need to manually connect to the relevant company server and folder each time you have logged in to the company network. It’s possible to mitigate this by adding the server in question to your login items (shown also below), however this isn’t a perfect workaround, particularly if you sometimes work away from the office and thus need to connect to VPN before (manually) reconnecting to the company server with its SAPUI files.

The other disadvantage (affects the author, but probably not too many other people) is that if you are yourself doing various proof-of-concept activities around SAPGUI for Java, then it gets a bit complex when the local config is used on top of the server config option (more on that later).

Although MacBooks come with default support for the Samba protocol (“smb://…”), however according to my smoketesting and according to the below discussion on sap.com, the SAPGUI for Java for MacBook app does not support Samba:

https://answers.sap.com/questions/12966811/does-sap-gui-for-mac-750-rev-8-support-network-loc.html

As the SAP employee replies to the questioner:

“according to chapter “3.4.1 Providing Connection” of the manual:

Depending on the location of the configuration file, you can enter either a full pathname (for a local file) or an URL (for a file located on an intranet web server).

Latter means http or https URL.

smb:// is not supported. What might work is to have the share already mounted and use something like file:/Volumes/whereitismounted/configfile.txt

But this assumes it is already mounted and is expected to be not really reliable.”

If in your organisation there would be an identified need for the MacBook SAPGUI users to get their Landscape file from a server without having to assign the network location to /Volumes manually, then it would likely be a server running a lightweight HTTP server, so that we could use the HTTP protocol. Technically this is not so difficult to achieve, but anyway out of scope for this blog, especially as there are many ways and many OS choices to make here; instead, we show how to use the Volumes approach for Samba protocol.

So imagine that the location of the xml files is here:

[Windows:]

\\orga.nisat.ion\some-drive\001\SAPstuff\SAPUILandscape\

The equivalent URL in Samba format [Unix/Linux:]

smb://orga.nisat.ion/some-drive/001/SAPstuff/SAPUILandscape/

In MacBook, from Finder use the top-bar menu Go -> Connect to Server… connection string is in the Samba format; now you will be connecting to some Windows share or folder using Samba protocol, and what happens here is that macOS mounts the share or folder in question to /Volumes on your local MacBook.

For command-line aficionados, there are also ways to accomplish this connection and mounting to /Volumes from Terminal, the simplest is probably this way:

open smb://orga.nisat.ion/some-drive/001/SAPstuff/SAPUILandscape/

So with the relevant SAPUILandscape folder on the server mounted to /Volumes, now we can from SAPGUI app go to top-bar menu SAPGUI -> Preferences and in the Configuration -> Logon screen we put the Volumes-based filepath as value of the field “SAP UI Landscape” and press Apply, and then our client gets its Landscape file from the Windows server like almost everyone else does. So if the server “drive” is defined as (the last directory in path):

smb://orga.nisat.ion/some-drive/001/SAPstuff/SAPUILandscape/

…then the filepath in Volumes to a relevant xml file will be something like this:

/Volumes/SAPUILandscape/SAPUILandscapeGlobal.xml

(If you used NFS to connect to your server, then it could be that you can specify the “nfs://…” formatted filepath, or maybe just the plain filepath without prefix, in SAPGUI Preferences – I cannot test this at the time of writing, but if anyone does that test then feel free to leave a comment with the results and then we can modify this paragraph).

Detour about side-effects of explicitly specifying the xml file to use

[Begin-of-Detour:

It seems that after specifying own file (whether on the server, or even just your own local file) in Preferences, then trying to switch back to use another file, nothing found, or old default location file still there and that is what gets modified instead of our specified file… also it can be difficult to go back to “empty” state as no way to remove the “uploaded file” data … all seems a bit strange.

So the logic of this, how to explain (even to myself 😂 )… for example if I create (as a copy of default file) the SAPGUILandscapecopy.xml and explicitly reference it in SAPGUI Preferences, and (say) delete the SAPGUILandscape.xml file, then what happens is that the SAPGUILandscapecopy.xml file that is specified in Preferences becomes an “Included [read-only] file” for the new (if just deleted) or updated (if still existing) default SAPGUILandscape.xml file:

Note the part that says

Include url=“file:/Users/myhomedir/Library/Preferences/SAP/SAPGUILandscapecopy.xml”

[BTW we don’t usually want to start specifying our own custom names of local files, the above was just for demonstration purposes; usually it just gets messy, having e.g. one read-only local file included as a reference from the default other local file].

So what the Include-logic means is that for items of the Included file, you cannot edit or delete any such items. On the other hand, you can still create new items or create a duplicate of existing items, and any such new or duplicated items are then editable and deletable.

So typically you would have the remote server file being specified in Preferences, and then any new or copied-then-modified items that you create, are being saved locally in SAPGUILandscape.xml (though most users will not need or want to make new entries).

But if you ever make the mistake of putting the local SAPGUILandscape.xml file itself as the file in Preferences, then that whole file becomes read-only and you cannot do anything with it, and it seems not to even save any new additions – I suspect it becomes somehow syntactically broken from the point of view of our client SAPGUI app as it is including itself as read-only. Never mind, you can still get out of this trap – so long as you have either a remote server filepath via /Volumes or a non-corrupted local backup file – as follows: empty the Preferences field for SAP UI Landscape and Apply; then close SAPGUI for Java. Then delete the useless SAPGUILandscape.xml file, and reopen SAPGUI, then you will see that a new empty default file is “under creation” (saved to file when you close SAPGUI again):

Now you can either open SAPGUI and specify the remote file again (the Server Option); or, you can rename some appropriate backup file to be the SAPGUILandscape.xml file (if you are going for The Local Option), and open SAPGUI for Java – in that case the local file once again becomes writable.

Anyway, the main idea is that since in Preferences you would be more likely to specify a file on the corporate server, then this file should of course be read-only (since changes made to the file on the server would affect all SAP users, i.e. thousands of people)… probably that is why the rule is, that any specified file in Preferences field “SAP UI Landscape” becomes an included, read-only file which is then “called” or “read in” by a created or updated (local) SAPGUILandscape.xml file, the default local file which is always existing (recreated by the app if necessary).

So in summary: the local file wraps the specified “remote” file, and changes can only be made by creating new items (including duplications of read-only items), where all the new items are saved to the local file.

End-of-Detour].

To reconnect the server to /Volumes when logging in, you can do that as follows – open System Preferences -> Users & Groups -> Login Items. From Finder where you can see e.g. the SAPUILandscape Drive-icon, so click and drag that icon into Login Items. You end up with something like this:

Remember though that this automatic reconnection is only going to work if you already have a connection to the organisation’s network from more or less as soon you logged in to your MacBook, in practice that usually means being on the Office LAN i.e. on-site; typically when off-site, connecting e.g. via VPN to company network involves manual steps requiring 2FA, so in these cases the connection will not happen immediately after logging in to MacBook, and hence the reconnection to server fails:

… in these cases, you can still connect manually to the server using the ways described above, after you have established a VPN connection.

To find the SAPUILandscape folder as a Volume, you can do that by going to the root drive (e.g. Monterey HD, usually the name reflects the version of macOS), then make hidden folders visible (Command-Shift-<the dot character>), and from there you find /Volumes and your mounted drive (folder).

You can skip forward now to the section “Visibility of items tip”, or you can read the following section about other main option for getting the xml file with the SAP system details.

The Local Option

The main advantage of The Local Option is that you don’t need to think about making sure, every time you login, that the folder you need access to is mounted to /Volumes.

Another advantage for a few people, is that keeping everything in the local file and using backups properly, is the neatest way for doing any POC work with the xml file. But for most people, this flexibility of the local option is neither useful nor needed.

The main disadvantage of the local option, is that eventually your local file contents will diverge from the server-maintained file, so if e.g. the logon details change for some SAP system on the server file, and you have only stale local information, you could be wondering “why can I not connect when everyone else can?”… so that’s something to bear in mind, that occasionally you might want to retrieve from the server the latest version of the relevant SAPUI xml file, and make that the new local file using move or copy commands (shown below).

[We note here that in SAPGUI for Java documentation, and for the actual default local file used by the SAPGUI for Java app, the main xml filename begins “SAPGUI…”; whereas in SAPGUI for Windows documentation, the main xml filename begins “SAPUI…” (<- no “G”). The thing to remember, is that we are using SAPGUI for Java, and therefore we must keep our local SAPGUI client software happy, by sticking with the “SAPGUI…” naming convention here; in fact the locally generated default file of the SAPGUI for Java app, is always called “SAPGUILandscape.xml”].

So let’s assume that you copy-pasted from the remote server, the SAPUILandscapeGlobal.xml file or whatever file it is you need. Once you have that “SAPUI…” xml file, in Terminal go to location ~/Library/Preferences/SAP:

cd ~/Library/Preferences/SAP

First backup the existing file in this directory, which is called “SAPGUILandscape.xml”, by renaming it to something like “SAPGUILandscape.xml_bac”:

mv SAPGUILandscape.xml SAPGUILandscape.xml_bac

If your SAPUILandscapeGlobal.xml file is, say, in Downloads, then copy it across to our SAP Preferences directory we are in, like so:

cp ~/Downloads/SAPUILandscapeGlobal.xml .

(Note the space followed by a dot character “ .” after the name of the file to be copied, this space plus dot tells the computer to copy the file to the current working directory the user is in).

Then, rename the copied file to be the new “SAPGUILandscape.xml” file, e.g.:

mv SAPUILandscapeGlobal.xml SAPGUILandscape.xml

See the “Detour” section above for advice about using the Preferences Logon tab… I strongly recommend that if you are using the Local Option, you don’t explicitly specify any file in that Logon tab, instead you should just leave it empty. If you want to work with multiple local files, the best way to manage this, is to have custom names for those files; then backup the current SAPGUILandscape.xml file, and copy the custom file you want to work with to become the current default file… for example:

mv SAPGUILandscape.xml SAPGUILandscape.xml_bac_20220304_v01

cp SAPGUILandscapeMyPrecious002.xml SAPGUILandscape.xml

In other words, you switch among your files in such a way, that the SAPGUI client app is always using the default file SAPGUILandscape.xml – this way you avoid the “Include [read-only” complexities mentioned in the “Detour” section.

Visibility of items tip

Now, if you have specified either via The Server Option or The Local Option a list of SAP systems in the xml file, and you open SAPGUI, it can happen that only some empty workspace appears; if this happens, then go to View -> Show All Workspaces, and then the full list of SAP systems should be visible under the relevant workspace(s).

If you are not using SSO to login to SAP systems, then now you can double-click on the SAP system you want to logon to… in that case you can skip forward to the section “And Logon…”

SAP Secure Login Client

If your organisation is using SAP SNC (Secure Network Connection) to enable SSO (Single Sign-On) then it means you need to do some SPNego/Kerberos type of negotiation between SAP Secure Login Client (3.0 as of Feb 2022) and the corporation’s authentication-servers. In that case, trying to login now to SAP without having the SAP Secure Login Client installed, will fail with an error message referring to SNC.

However, no need to worry. Instead, what we need to get hold of now, is this thing the cool kids are calling “SAP Secure Login Client”. Again, there are the two main ways to get this, either you have the right kind of S-user and can get it yourself, or you don’t and in that case you need to find someone who can get it for you. Anyway, I describe how to get said software from the same software downloads site where we got the SAPGUI jar earlier.

So from https://launchpad.support.sap.com/#/softwarecenter

we can use search term “SAP Single” and from the Categories offered choose latest main version of SAP Single Sign On (3.0 as of March 2022), with the “Maintenance Product” type, like so:

From there choose “Comprised Software Component Versions”, and from there “Secure Login Client 3.0”. Then make sure to choose “MAC OS” in the dropdown box, since “WIN 32” will not at all get you the stuff you need here  … and choose the latest version, and download it using I-Ching icon or Download Basket:

Once you unzip the downloaded file, you can see it contains an installer pkg. So, double-click on it and follow the installer steps, it should install ok.

Next, I recommend to logout, and log back in again. If you are working remotely, make sure after logging in again that you have (re-)connected to the corporate network using VPN. (Because it is only if your computer is connected to corporate network, that the Secure Login Client is going to be able to get the stuff it needs to do secure login).

Once connected to corporate network, you can (if you like, but see below) open the new app “Secure Login Client”. Just remember to keep it open for as long as you intend to use SAPGUI SNC connections to SAP systems.

But actually, you don’t even need to open the Secure Login Client manually. Instead you can just leave it alone, then when via SAPGUI you double-click on some SAP system you want to logon to, SAPGUI itself realises that it has to open Secure Logon Client, and it does that successfully, so you should see the Secure Logon Client logo (a white tick on blue background) in the MacBook top menu bar:

..and thanks to the Secure Login Client, you should now be able to logon to your SAP systems.

And Logon…

Note that the first time that you logon to an SAP system from SAPGUI for Java, you are asked to assign a Trust Level Classification to the system you are accessing… for example you could accept the default value “Internal: Generally trusted…” and continue by pressing “OK”:

This Trust Level Classification for an SAP system can be edited later (when a user session in SAPGUI is open for said SAP system), either by menu path (SAPGUI top bar menu) File -> Edit Trust Level, or by using the Edit Connection button and go to Security tab. For example, you might want SAP to be able to download or upload files on your MacBook – generally, it is ok to assume that SAP systems of your own organisation have no malicious intent towards you.

If you want to investigate and/or configure the Trust Level concept in greater detail, go to SAPGUI -> Preferences -> Trust Level Editor.

So anyway, the main result here of interest is that now we can really connect to SAP systems using SAPGUI for Java for macOS… quod erat demonstrandum:

If you get redirected to the Sign-In Screen of the SAP System instead of seeing the main landing screen, it means that SSO failed; the usual reason would be because you have no SAP user ID associated with the default client of the SAP System you are trying to log into. In that case, you should contact your organisation’s SAP Authorisations team for advice.

By the way, if you try to Quit SAPGUI when there is a SAPGUI user session open for one or more SAP systems, you get a popup warning that you might lose data. Also, if you go ahead and close SAPGUI without logging off SAP, those sessions are left “headless” until usually they time-out, so the wise procedure is to always first logoff SAP sessions in the normal manner (System -> Log Off) before shutting down the SAPGUI client.

Reinstalling the SAPGUI for Java for MacBook software

In case you want or need to reinstall SAPGUI for Java (e.g. you got in a mess with the Server and/or Local Options and files), then here are the steps:

(a) Delete the SAP Clients folder containing the SAPGUI for Java app components from Applications folder

(b) Delete all the config (but make sure to first take backups of any local xml file you want to use later and/or have a downloaded copy of the server file) – you can delete the config this way:

rm -rf ~/Library/Preferences/SAP/

(c) Reinstall the SAPGUI client and get any needed local xml files back into the (regenerated via install) folder: ~/Library/Preferences/SAP/

–EndOfFile