This is the fifth of a six-part series bringing us from initial download and installation through to scripted packages and distribution to clients. In this part we'll cover how Package Event Scripts can help maintain central control of the SAP Logon configuration as well as explore some SAPGUI customizing.
As parts of this process are likely already familiar to many of you, I have broken it up into stages. Please feel free to jump to the sections most relevant for you. If you are setting up an Installation Server for the first time, however, I recommend you start with SAPGUI Installation Server Part 1 - Getting Started and move sequentially through the steps.
- Getting Started
- Includes download of all required files
- Initial Installation
- Patching
- Package Creation
- Includes initial installation of the administrator's SAPGUI
- Scripting (this document)
- LSH and Distribution
Scripting
If you are continuing on from the previous step (SAPGUI Installation Server Part 4 - Package Creation), then you have created a Package called Basic with several SAPGUI components in it, and you have installed SAPGUI on your own workstation using the Basic Package. You don't yet have any entries in SAP Logon, however. Now it's time to create those entries in a central configuration file that you can share with your users.
Create Shared Configuration Files
The connection data for SAPGUI is stored in a file called saplogon.ini, and additional data about how connections are organized and displayed in SAP Logon is stored in SapLogonTree.xml. Depending on options you set within SAPGUI or SAP Logon, there may be other configuration files as well, but these two are the ones of primary concern. By default, when SAPGUI 7.30 (or 7.20) is installed on a Windows 7 system, these two files will be created in:
- C:\Users\<username>\AppData\Roaming\SAP\Common
On Windows XP (from which hopefully by now all of you have migrated away, right?) the path would have been:
- C:\Documents and Settings\<username>\Application Data\SAP\Common
Older SAPGUIs used a different storage mechanism, and so if you upgrade from one of these to 7.30, saplogon.ini may still be found in the old locations (or may be copied from the old location to the new location). SAPGUI 7.10 stored saplogon.ini in the program's installation folder (C:\Program Files\SAP\FrontEnd\SAPGUI (on 32-bit; for 64-bit machines substitute Program Files (x86) for Program Files), while SAPGUI 6.40 and earlier stored it in C:\Windows.
In many organizations, the administrator would create a default saplogon.ini and use scripting to push it to the client workstation in the appropriate folder during the SAPGUI installation. This worked well for new installs, but it didn't help much with upgrades, or for distributing changes when the server landscape underwent a change. Then the administrator would be required to use new scripts to push out new copies of the file, which would overwrite any customization the end user may have made. Furthermore, the end user might change the file inadvertently, modifying or deleting an entry unintentionally, invariably resulting in a call to the Help Desk. In this case, the administrator might have to resort to walking the user through editing their own settings to get things working again.
SAPGUI 7.30 offers a better way. It is now possible to store saplogon.ini and SapLogonTree.xml in a shared location on a server and configure SAP Logon on the workstation to use these shared files instead of the local ones. This means that all users are always using one version of the truth as defined by you, the system administrator. If you need to distribute a landscape change, you only need to edit one set of files in one location, and all users will immediately see the change without having to do anything on their workstations.
We'll discuss how to configure SAP Logon to use the shared files in a moment, but first we need to set up the server location and create the two configuration files to put there, and the first part of that is to configure our own SAPGUI, just installed on our workstation.
Edit Services File (optional)
If you use Logon Groups for message server-based load balancing or for directing different user groups to different application servers (configured via transaction code SMLG), then there are one or more additional entries which you will need to make to the services file which are not made by NwSapSetup during the base SAPGUI install. Later you will use your Package Event Scripts to push this change to your users, but first you must make the change manually to your own workstation.
If you don't use Logon Groups, you can skip this step.
On your workstation, navigate to:
- C:\Windows\System32\drivers\etc
There you will find a text file called services. You can examine it with Notepad, but in order to edit it in Windows 7 you must first open Notepad with Administrator privileges. This is because services is a protected operating system file, and making a mistake with it could negatively impact Windows (as well as SAPGUI) operation. Windows XP does not have this restriction, so you may simply open the file with Notepad and edit away.
In Windows 7, click Start... All Programs... Accessories and then right-click Notepad. In the context menu choose Run as administrator and confirm Yes at the prompt. In Notepad, choose File... Open and navigate to the services file you located earlier.
Be careful not to change any of the lines in the file. Scroll to the end, where you will see numerous lines added by the SAPGUI install. At the end of the list, add a new line something like the following:
sapmsSID 36nr/tcp
In this example, SID represents the System ID of your load-balanced system and nr represents the System Number. So, if your System ID is PRD and System Number is 00, the line will be
sapmsPRD 3600/tcp
For the blank space between 'sapmsSID' and '36nr/tcp' you can use either a TAB or hit the SPACEBAR a few times; it doesn't matter. Be sure to hit ENTER at the end of the line, so that the last line of the file is a blank line.
So, when you're done, the last few lines of your services file may look something like:
sapgw98 3398/tcp
sapgw99 3399/tcp
sapmsPRD 3600/tcp
Save the file.
Create CustomerFiles Folder
Now you need to create a folder on your server that your users will have read-only access to. I recommend putting this folder under the root of your Installation Server share, as your users already have this access there. Furthermore, I recommend calling the folder CustomerFiles (exactly like that) for the very specific reason that later, if and when you make a self-extracting single-file-installer, such a folder will be automatically included in the single-file-installer. If you call the folder something else, such as ConfigFiles (as some of the documentation shows in examples), it will not work with single-file-installers.
So, navigate to your Installation Server at \\server\sapgui, and create CustomerFiles there. When you are done, the contents of your sapgui share will look something like this:
![]()
Start SAP Logon with Command-Line Switch
The next step is to start SAP Logon in such a manner that it will create a new set of configuration files in the CustomerFiles folder. You will want to have an easy way of doing this whenever you need to make changes to the published SAP Logon configuration, so I recommend making a small batch program and saving it on your Desktop.
Right-click on your Desktop and choose New... Text Document. Rename the new document to saplogon_ini_file.cmd and confirm the prompt for changing the file extension. Right-click on saplogon_ini_file.cmd and choose Edit. Put the following lines into your new batch program:
C:
cd \Program Files (x86)\SAP\FrontEnd\SAPgui
saplogon.exe /ini_file=\\server\sapgui\CustomerFiles\saplogon.ini
If you are working on a 32-bit machine, change Program Files (x86) to Program Files. Remember to substitute your server's hostname for server.
Save your changes and close the editor. Now you have an easily-accessible and quick way of starting SAP Logon in such a way that you will be able to edit the configuration. Let's do that now. Double-click your batch file to execute it and start SAP Logon.
Create Connection Subfolders and Entries
Although it is optional to do so, if you have numerous SAP systems, or systems of different types or purposes that can be logically grouped, then you may want to make the organization easier for your users by creating an hierarchical folder structure for the connections. However, you can also just create a flat structure of all relevant systems without any subfolders.
In SAP Logon, highlight the Connections folder. Right-click it and choose Add new subfolder.
![]()
Give the new subfolder an appropriate name and click OK.
![]()
Single Application Server
To add a direct connection to a specific application server, or a system without any load balancing, select your new subfolder and click on the New icon.
![]()
The Create New System Entry window will open. Click Next.
![]()
On the next screen, set Connection Type to Custom Application Server, type in an appropriate system name to be displayed to users in the Description field, and fill in the relevant connection information for Application Server, Instance Number, and System ID. If a SAProuter sits between your users and the server, fill in the information needed for that; otherwise, leave SAProuter String blank.
![]()
Optionally, you may check the box for Use this page as the first page for subsequent entry creations to skip the first screen next time. I recommend using fully-qualified domain names for the Application Server, but depending upon your local network configuration it will usually work just as well with an unqualified hostname. Click Finish.
Load-Balanced Group
You are now back in the SAP Logon window. If you additionally (or instead) need to set up a load-balanced system connection, click on New again just as before to launch the Create New System Entry dialog. On the System Connection Parameters page, this time you will make a different selection for Connection Type, and as a result you will have some different fields to fill in.
For Connection Type select Group/Server Selection. Enter an appropriate Description, type in the System ID, and give the fully-qualified domain name (or simple hostname) for the Message Server of your load-balanced system group. Click the drop-down arrow for Group/Server and you should see a list of the defined logon groups as well as the individual application servers that make up the system. Choose the group you intend to use (previously created in SMLG).
![]()
You should now see the systems and/or groups you defined in SAP Logon.
![]()
Close SAP Logon to save your changes to the configuration files.
Sample Configuration Files
You should now see two files created in your CustomerFiles folder on the server:
- saplogon.ini
- SapLogonTree.xml
There is nothing more you need to do directly with these files, but if you open them you will see, among other things, entries similar to the following:
saplogon.ini
[Server]
Item1=public
Item2=qas-server.domain.org
[Description]
Item1=Production
Item2=Quality Assurance
[Address]
Item1=xx.xx.xx.xx
Item2=
[MSSysName]
Item1=PRD
Item2=QAS
[MSSrvName]
Item1=prd-msgsvr.domain.org
Item2=
[MSSrvPort]
Item1=sapmsPRD
Item2=
Notice that last group for MSSrvPort, and how the Item entry for your load-balanced group uses the TCP port name that incorporates the System ID. This port name is then referenced to the entry you manually created in your services file to find the actual TCP port number (in this example, and in most systems, it would be 3600).
SapLogonTree.xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- SAPGUI for Windows 7300 4 29 5 2014 10:1:27 Pacific Standard Time -->
<SAPTREE version="7300.3.8.1085">
<Files>
<File name="saplogon.ini" type="Connections"/>
<File name="sapshortcut.ini" type="Shortcuts"/>
</Files>
<Nodes>
<Favorites name="Favorites" uuid="..." expanded="1"> </Favorites>
<Shortcuts name="Shortcuts" uuid="..." expanded="1"> </Shortcuts>
<Connections name="Connections" uuid="..." expanded="1">
<Node name="ERP" uuid="..." expanded="0" memo="">
<Item name="Quality Assurance" type="connection" uuid="..."/>
<Item name="Production" type="connection" uuid="..."/>
</Node>
</Connections>
</Nodes>
</SAPTREE>
From this you can see how the XML file defines the folder structure you see in SAP Logon.
How to Use Server Configuration Files
Now that you have configuration files to share, how do you configure your users' SAPGUIs to use them? One way is via SAP Logon Options, which is accessed by clicking the icon in the upper left corner of SAP Logon, then choosing Options in the drop-down box.
![]()
![]()
On the screen that opens, drill down to SAP Logon Options... Server Configuration Files and then in the field XML Configuration File on Server type in the path to your XML file: \\server\sapgui\CustomerFiles\SapLogonTree.xml.
![]()
However, you don't want to run around to every user's workstation and configure that option, so there's a better way. This parameter, like most of the others that can be set via SAP Logon Options or SAP GUI Options, is maintained in a registry setting, and registry settings can be configured by Package Event Scripts.
Create Package Event Scripts
Open up the Installation Server Administration Tool (NwSapSetupAdmin):
- \\server\sapgui\Setup\NwSapSetupAdmin.exe
Switch to the Packages tab, select your Package, and switch to the Package Configuration tab. Toward the bottom of the screen you will see a series of tabs labeled On Installation Start, On Installation End, On Uninstallation Start, On Uninstallation End, On Update Start, and On Update End. There is also a small link to the right just above them for Expand Editor. Click that to make it a little easier to work in the script editors.
![]()
As the tab names imply, here you can enter scripts that will execute during the install (or uninstall or patch update). Upgrades execute the 'install' scripts, whereas patch updates execute the 'update' scripts. For now, we will focus on Installation. You can have two scripts, one that will execute nearer to the beginning of the installation, and one that executes at the end as a wrap-up. Depending on the functions you intend to execute, one or the other may be more appropriate.
Package Event Scripts are essentially VBscript and follow VBscript conventions. Some additional shell options have been preset by the install program, which unfortunately are not well documented, but you can get an idea of the possibilities from the SAP Setup Guide located at the root of your Installation Server share, in chapter 3.6.2, or by clicking the link for Insert Script Sample and examining (and adapting) the code snippets found there. The samples include functions for adding custom logging to the setup log file, checking files and registry keys for existence, manipulating files and registry keys, and so forth. Much of the scripts you will see below are adapted from these script samples.
On Installation Start
First we'll look at some code to execute at the beginning of your installation. The purpose of this piece of code is to duplicate the manual work you did earlier on your own workstation, editing the services file to put the logon group TCP port entry into it. Again, if you don't use logon load balancing or logon groups, then you don't need this script at all. This is adapted straight from the script examples.
The script begins by writing to the setup log file. Every time we write to the log we prefix the line with "Event: " as a way of making our custom log entries searchable. We let anyone reading the log know that this is where the "On Installation Start" script is running. We include some comments in the script to let future sysadmins know what's going on, then write a log entry to say exactly what we're doing. We resolve the %WinSysDir% environment variable and add the rest of the path to the services file and put that into the strFile variable. Here, the sapsetup program provides some useful text file parsing utilities, and we make use of those. We look in the services file to see if a line with our desired entry of "sapmsPRD" exists already. If it does, just to be safe, we replace the line entirely, just in case it exists with an incorrect TCP port number. If it doesn't exist, we add the line. That whole part is encapsulated in an If... Then structure as a way of capturing any error in finding the services file.
-------------------
NwEngine.Context.Log.Write "Event: On Installation Start"
'Check whether a line containing the string "sapmsPRD" exists.
'If so, replace that line with
'"sapmsPRD 3600/tcp"
'otherwise simply append the new line to the end of the services file.
NwEngine.Context.Log.Write "Event: Appending or replacing lines in the services file"
strFile = NwEngine.Variables.ResolveString( "%WinSysDir%\drivers\etc\services" )
Set objTextFile = CreateObject("NwSapSetupATLCommon.TextFileParser")
If objTextFile.Parse( strFile ) Then
NwEngine.Context.Log.Write "Event: Modify the file " & Chr(34) & strFile & Chr(34)
If objTextFile.DoesStringExist( "sapmsPRD" ) Then
objTextFile.ReplaceLineEx "sapmsPRD", "sapmsPRD 3600/tcp"
Else
objTextFile.AppendLine "sapmsPRD 3600/tcp"
End If
objTextFile.Save( strFile )
Else
NwEngine.Context.Log.WriteWarning "Event: Could not open the file " & Chr(34) & strFile & Chr(34)
End If
-------------------
That's it. That's the entire script. You can add more if you wish, but this script will execute as it stands.
On Installation End
Now we get to the meatier part of our scripts. After the installation is essentially complete, we want to configure the user's SAP Logon to use our shared server configuration files created earlier.
This script first checks to see whether this option has already been set in the registry hive HKEY_CURRENT_USER, as that setting will take precedence if it exists. We don't want that, we want all users of the workstation to use the same shared files, so we want to set the key in HKEY_LOCAL_MACHINE and make sure it isn't set in HKEY_CURRENT_USER. So, the first step is to check if it's there, and if found, delete it.
Note that in Package Event Scripts, as in VBscript, you can abbreviate the registry hives to HKCU and HKLM.
Next we need to know whether we are running in a 32-bit or 64-bit version of Windows, as that influences the correct path to the registry key in HKLM (but not in HKCU). Because SAPGUI is 32-bit software, if it is installed in 64-bit Windows, it will be registered, along with all other 32-bit software, in HKLM\Software\Wow6432Node. If we are in 32-bit Windows, it will be directly under HKLM\Software. We check WMI (Windows Management Instrumentation) to determine the AddressWidth with a pair of functions that return a TRUE or FALSE result. Based upon the result, we set a variable for our registry path appropriately. This particular method of determining the OS address width is based upon some ideas developed by DavidRR at StackOverflow (User DavidRR - Stack Overflow).
Having set our registry path appropriately, we set the registry value HKLM\Software<\Wow6432Node>\SAP\SAPLogon\Options\ConfigFileOnServer to point to \\server\sapgui\CustomerFiles\SapLogonTree.xml, and we're done! If we want to set other registry values, we would do so here, but this was our primary objective, so let's take a look at the code.
-------------------
NwEngine.Context.Log.Write "Event: On Installation End"
'Redirect SAPLogon to server configuration file but allow local custom entries
If NwEngine.Shell.RegValueExist("HKCU\Software\SAP\SAPLogon\Options\ConfigFileOnServer") Then
NwEngine.Context.Log.Write "Event: Deleting Previous HKCU ConfigFile Value"
NwEngine.Shell.DeleteRegValue("HKCU\Software\SAP\SAPLogon\Options\ConfigFileOnServer")
End If
Function Is32BitOS()
Const Path = "winmgmts:root\cimv2:Win32_Processor='cpu0'"
Is32BitOS = (GetObject(Path).AddressWidth = 32)
End Function
Function Is64BitOS()
Const Path = "winmgmts:root\cimv2:Win32_Processor='cpu0'"
Is64BitOS = (GetObject(Path).AddressWidth = 64)
End Function
If Is64BitOS Then
NwEngine.Context.Log.Write "Event: 64-bit OS detected"
strRegPath = "HKLM\Software\Wow6432Node\SAP\"
ElseIf Is32BitOS Then
NwEngine.Context.Log.Write "Event: 32-bit OS detected"
strRegPath = "HKLM\Software\SAP\"
End If
strRegConfigValue = strRegPath + "SAPLogon\Options\ConfigFileOnServer"
strXmlFile = NwEngine.Variables.ResolveString("%SapSrcDir%\CustomerFiles\SapLogonTree.xml")
NwEngine.Context.Log.Write "Event: Pointing SAPLogon to Server Configuration Files"
NwEngine.Shell.SetRegValue strRegConfigValue, "REG_EXPAND_SZ", strXmlFile
-------------------
If you have multiple Installation Servers, each with its own different CustomerFiles folder and different saplogon.ini settings, the user will be pointed at the saplogon.ini within the Installation Server being used, even without changing a line of code in the script. That's where the %SapSrcDir% environment variable comes into play.
Optional Registry Settings for Interface Layout
Now that you have a method for setting registry values during the installation, there are many other settings which you might choose to preconfigure. For instance, you might choose to resize the SAP Logon window and reposition the column widths to make it a bit more user-friendly out of the box. You might choose to maximize the SAPGUI window the first time it's opened. You might want the Transaction Code entry box to be open by default, and the system information in the status bar to show. For users who frequently have sessions open to multiple systems, it can be useful for the Windows Taskbar to display some system information when the mouse hovers over it. So, here are some registry settings, and the Package Event Script code to set them, that I find useful for an initial SAPGUI install. Note that while I would put the script above for the config file location into both On Install and On Update scripts, the following is something I would only put into On Install. Once SAPGUI is installed, users are likely to customize it to their own liking, so you don't want to overwrite their customizations with your defaults every time you push out a patch.
-------------------
'Configuring window size and SAPLogon option initial defaults
NwEngine.Context.Log.Write "Event: Setting Registry Values for SAPLogon Options"
strRegSapFrontPath = "HKCU\Software\SAP\SAPGUI Front\SAP Frontend Server\"
strRegSapLogonPath = "HKCU\Software\SAP\SAPLogon\Settings\"
strRegTaskbarTitle = strRegSapFrontPath + "Administration\ShowAdditionalTitleInfo"
strRegCmdLine = strRegSapFrontPath + "Customize\ShowCmdLine"
strRegStatusBar = strRegSapFrontPath + "Customize\Statusbar.Layout"
strRegShowKeys = strRegSapFrontPath + "Customize\Dropdown.ShowKey"
strRegSortKeys = strRegSapFrontPath + "Customize\Dropdown.SortKey"
strRegGuiWindow = strRegSapFrontPath + "Window\Maximize"
strRegSplitPos = strRegSapLogonPath + "SplitterPosition"
strRegBottom = strRegSapLogonPath + "Connections\Bottom"
strRegCol1 = strRegSapLogonPath + "Connections\ColumnWidth1"
strRegCol2 = strRegSapLogonPath + "Connections\ColumnWidth2"
strRegCol3 = strRegSapLogonPath + "Connections\ColumnWidth3"
strRegCol4 = strRegSapLogonPath + "Connections\ColumnWidth4"
strRegCol5 = strRegSapLogonPath + "Connections\ColumnWidth5"
strRegCol6 = strRegSapLogonPath + "Connections\ColumnWidth6"
strRegCol7 = strRegSapLogonPath + "Connections\ColumnWidth7"
strRegLeft = strRegSapLogonPath + "Connections\Left"
strRegRight = strRegSapLogonPath + "Connections\Right"
strRegTop = strRegSapLogonPath + "Connections\Top"
strRegNode = strRegSapLogonPath + "LastSelectedNodeKey"
'SAP Logon Options, Interaction Design, Visualization 2, Show system name in taskbar button
NwEngine.Shell.SetRegValue strRegTaskbarTitle, "REG_DWORD", 1
'Open Transaction Code Entry Field
NwEngine.Shell.SetRegValue strRegCmdLine, "REG_DWORD", 1
'Display Information in Status Bar
NwEngine.Shell.SetRegValue strRegStatusBar, "REG_DWORD", 1
'Interaction Design, Visualization 1, Show keys within dropdown lists
NwEngine.Shell.SetRegValue strRegShowKeys, "REG_DWORD", 1
'...Sort by keys within dropdown lists for most efficient keyboard input
NwEngine.Shell.SetRegValue strRegSortKeys, "REG_DWORD", 1
'Maximize SAPGUI window
NwEngine.Shell.SetRegValue strRegGuiWindow, "REG_DWORD", 1
'Set SAPLogon window and column options
NwEngine.Shell.SetRegValue strRegSplitPos, "REG_SZ", "19"
NwEngine.Shell.SetRegValue strRegBottom, "REG_SZ", "523"
NwEngine.Shell.SetRegValue strRegCol1, "REG_SZ", "195"
NwEngine.Shell.SetRegValue strRegCol2, "REG_SZ", "25"
NwEngine.Shell.SetRegValue strRegCol3, "REG_SZ", "37"
NwEngine.Shell.SetRegValue strRegCol4, "REG_SZ", "206"
NwEngine.Shell.SetRegValue strRegCol5, "REG_SZ", "26"
NwEngine.Shell.SetRegValue strRegCol6, "REG_SZ", "164"
NwEngine.Shell.SetRegValue strRegCol7, "REG_SZ", "25"
NwEngine.Shell.SetRegValue strRegLeft, "REG_SZ", "169"
NwEngine.Shell.SetRegValue strRegRight, "REG_SZ", "1059"
NwEngine.Shell.SetRegValue strRegTop, "REG_SZ", "213"
NwEngine.Shell.SetRegValue strRegNode, "REG_SZ", "de4aeca7-6c46-49f8-bf55-ba5ae43537ca"
-------------------
A note about that last line with the UUID ("de4ae..." etc). This line sets the cursor focus when SAP Logon is opened into the "ERP" folder we created earlier. You will need to open your SapLogonTree.xml file and look up the correct UUID for the node you want to have as the initial focus and use that in the place of the example I gave here.
Package Event Script Wrapup
Once you have entered your scripts, you just need to click on the Save button.
![]()
The Package Version will increment by 1 when you do this. Note that any clients (such as your own workstation) installed using this Package will now auto-update if the Package includes SAP Automatic Workstation Update (which our example does), either the next time the AWUS service starts, or within the defined interval for checking for updates (24 hours by default). However, such clients will only run the On Update scripts, not the On Install scripts.
Your Package, including scripts, is now fully defined. All that remains is to optionally configure Local Security Handling and then distribute the installation to clients.
<--->
Continue on to SAPGUI Installation Server Part 6 - LSH and Distribution.
