Deploying Options for Notes 8.x on Windows

Notes 8.x introduces a new user interface built on the IBM Lotus Expediter client platform, which in turn is built with Eclipse technology. This new layer is deployed through a process called provisioning which installs a large number of plugins and XML configuration files.

IBM calls this the Standard configuration. Notes 8.x can still run with the old familiar user interface, which is called Basic Configuration. There are separate install packages for Basic and Standard Configuration, but if you install Standard Configuration you can launch Basic Configuration later by adding "-basic" to the command line which launches Notes or by running nlnotes.exe directly.

The Basic Configuration installer does not contain any plugins and is smaller than the Standard Configuration. It does not use the provisioning process at all. You control the Basic Configuration installer mainly though command line arguments and through transform files created by InstallShield Tuner for Lotus Notes.

You control the new provisioned features in the Standard Configuration with command line arguments and customizations to install.xml and plugin_customization.ini. Generally, InstallShield Tuner has no control over the provisioning process or any feature built from plugins. The Sametime sidebar application and the IBM Lotus Symphony editors are provisioned features.

Several executable files are involved in a typical Notes deployment and most of them take command line parameters. The most important executables are the webkit, setup.exe and msiexec.exe.

A webkit is an executable package you can download from the Passport Advantage website. Each platform, language and version of the Notes client has its own webkit with a unique part number. The downloaded file uses the part number for the filename, such as C1SP4EN.EXE which is the webkit for Lotus Notes Client version 8.5.0, English, Standard Configuration for Windows XP and Vista.

Running the webkit unpacks dozens of install files to a temp directory and runs setup.exe, the Lotus Notes setup executable. On the Windows platform setup.exe launches msiexec.exe, better known as InstallShield.  

The command line arguments you use depend on the file you execute. For instance there are silent install arguments for all 3 executable files:

webkit:  -s

setup.exe:   /s

msiexec:    /qb+!

EXAMPLES:

   C:> c1sp4en.exe -d -s -a /s /v"/qb+!"

   C:> setup.exe /s /v"/qb+!"

   C:> msiexec.exe /i "Lotus Notes 8.5.msi" /qb+!

Notice that for a completely silent install you must pass the webkit arguments for all 3 executables and that the arguments are nested.

Important webkit arguments:

-d
  The webkit unpacks the Notes install package into a temp directory. This option tells the webkit to delete those files once the installation is complete. This must be the first argument in the command line.
-s
  Unpack the install package silently, do not prompt the user for the location of the temp directory.
-a
  Pass all of the following arguments to setup.exe. Without this switch the rest of the command line may be ignored.

Important setup.exe arguments:

/s
  Silent install. This argument suppresses all of the dialog boxes from setup.exe
/v""
  Pass everything within the double quotes to msiexec.exe. There is no space between the           letter v and the double quotes.

Important MSI arguments:

Silent Install Options.

/qn
  Completely silent. The user will not see any UI from InstallShield.
/qb!
  The user will see an InstallShield dialog with a progress bar. Without the ! the dialog will have a cancel button.
/qb+!
  The user will see the progress bar dialog and will get a popup window to notify them when the install is complete.



/i "Lotus Notes 8.5.msi"
If you run msiexec.exe directly you must pass the name of the Notes MSI file. This isn't used if you run the webkit or setup.exe.


TRANSFORM="Z:MyFileShareMyCustomNotes.mst"
If you created a custom MST using InstallShield Tuner for Lotus Notes you must use this argument to tell InstallShield where to find it.

PROGDIR="C:Program FilesmyDirNotes"

DATADIR="D:myDataNotesdata"

These two parameters let you control the install location of the Notes program files and the user's data directory from the command line. Enclose the path in double-quotes if it contains spaces.

These commands are ignored during upgrades; to change the installed Notes path you must uninstall and reinstall Notes.

ADDLOCAL=ALL

This argument can be used to install a feature such a Notes Single Logon service or the Domino Designer client. It cannot be used to install a provisioned feature like the Sametime sidebar. (Provisioned features are deployed as plugins using Eclipse provisioning technology.)

For more information see:
http://msdn.microsoft.com/en-us/library/aa367536.aspx

SELECTINSTALLFEATURES=FeatureOneID,FeatureTwoID

This argument specifies which Eclipse provisioned features will be installed.

If you do not pass SELECTINSTALLFEATURES and upgraded client will keep the features it currently has and they will be upgraded to the new version. New installations will use the defaults specified in install.xml to determine which features will be installed.

If you pass SELECTINSTALLFEATURES the client will have exactly those features you list when the install completes. Any existing features you do not list will be removed. Features marked as "required=true" in install.xml will always be installed.

EXAMPLE:

      setup.exe /s /v"SELECTINSTALLFEATURES=SametimeUI,Editors"

After upgrading the client will have the Sametime sidebar application and the Symphony editors installed. Because the "CAE" and "Activities" features are not on the list and are not marked as required in install.xml, they would be removed by the installer.

See install.xml for a complete list of features. The "id" attribute is the string you should use in the SELECTINSTALLFEATURES list.

ALLUSERS=1

This parameter puts the desktop icons into the All Users Windows profile, so that any Windows profile will see them on the desktop. Without this parameter, icons will be placed on the desktop of the Windows account running the installation. In the case of SUrunAs, that is probably the administrator, not the end user.

It never hurts to put ALLUSERS=1 onto the command line; if your test installation doesn't create desktop icons properly, you probably need to use this parameter.

EXAMPLE:

    setup.exe /s /v"ALLUSERS=1"

SETMULTIUSER=1

All notes installations are either single-user or multi-user installations. The install wizard offers the choice to install Notes "Just for this me" or for "Anyone who uses this computer" which correspond to single and multi-user installation.

Single-user installations usually have a data directory inside the Notes program directory. The default values are:

   C:Program FilesIBMLotusNotes

   C:Program FilesIBMLotusNotesData

Best practice is to allow only one person to use a single-user Notes client. Switching IDs is no longer recommended, use a multi-user client instead.

Multi-user installations have a separate data directory for each user. The default values are:

   C:Program FilesIBMLotusNotes

   C:Documents and Settings<username>Local SettingsApplication DataLotusNotesData

When you upgrade a Standard configuration multi-user client silently you must pass SETMULTIUSER=1 otherwise install will fail. You should never pass SETMULTIUSER=1 when upgrading a Single-user client; if you do install will try to convert the client to Multi-user and although the upgrade will be successful the user's data directory will not be migrated. The new data directory under C:Documents and Settings is essentially a brand new Notes client and the user will need to run through user setup the first time he launches Notes.

This presents a serious problem if you have a mixed environment and don't know which clients are single-user and which are multi-user. Currently IBM has no migration strategy to move from single to multi-user installation. (Create SPR enhancement request and insert link here!!!)

EXAMPLE:

   setup.exe /s /v"SETMULTIUSER=1"

The Basic configuration client install ignores this argument. To force a multi-user installation of a Basic configuration create a transform file as described in technote 1108178.

"How to perform a Notes multi-user installation as a command line base install"  Link

Also known as the install manifest, install.xml controls the default behavior of the provisioning process during installation or upgrade. It primarily defines which provisioned features must be installed, which are optional and which features should not be installed.

Each "installfeature" tag has several important attributes. Default specifies if the feature will be installed by default. Required features are always installed. Visible features will appear in the feature selection page of the InstallShield wizard. Visible has no affect on silent installs.

The "id" attribute can be used to reference the feature. This is the string used by the SELECTINSTALLFEATURES argument, for instance. SELECTINSTALLFEATURES overrides the default behavior defined by install.xml.

To modify install.xml run the webkit with no command line arguments. It will unpack the install package to a temp directory. Copy the package to another folder then cancel the installation. Find install.xml under the "deploy" directory and modify it as needed. You can either post the modified install package on a file share as is or you can use the SUsetRunAs wizard to collect it into a single executable.

Plugins may have configuration files in xml format. You can use plugin_customization.ini to set values in these configuration files at install-time. Look at the XML file to see the available attributes and values. This procedure may not work for some attributes.

EXAMPLE:

On an existing client open community-config.xml located in

   C:Program FilesIBMLotusNotesdata workspace.metadata.plugins com.ibm.collaboration.realtime.community.sametime

Notice the attributes used in the top level "community" tag. The "loginAtStartup" attribute controls whether the Sametime sidebar application logs in when Notes launches.

Open plugin_customization.ini and add the following line:

com.ibm.collaboration.realtime.community.sametime/loginAtStartup=true

Install will set the attribute to true for each client.

To modify plugin_customization.ini run the webkit with no command line arguments. It will unpack the install package to a temp directory. Copy the package to another folder then cancel the installation. Find plugin_customization.ini under the "deploy" directory and modify it as needed. You can either post the modified install package on a file share as is or you can use the SUsetRunAs wizard to collect it into a single executable.

Setup.ini

Every Notes install package has a Setup.ini file to control the behavior of setup.exe. This file can pass command line parameters to msiexec which makes it easy to handle complex command lines. Just put anything you would pass to msiexec on the CmdLine= line of Setup.ini.

[Startup]

CmdLine= TRANSFORMS=C:Test Notes 850myTransform.mst ALLUSERS=1 /qb+

Setup.ini can handle spaces in a file path without using double quotes as shown above. This is handy if you would need to pass double quotes on the command line, such as with the setup.exe /v"" parameter. The nested double-quotes in the following line are not allowed from a command prompt, use Setup.ini to pass those parameters instead.

setup.exe /v""TRANSFORMS=C:Test Notes 850myTransform.mst""

To modify Setup.ini run the webkit with no command line arguments. It will unpack the install package to a temp directory. Copy the package to another folder then cancel the installation. Find Setup.ini at the top-level of the install package and edit it using Notepad or another text editor. You can either post the modified install package on a file share as is or you can use the SUsetRunAs wizard to collect it into a single executable.

In this section we will walk through a complex install scenario and explain the specific steps needed for each install requirement. The examples are cumulative, but each will highlight the new steps required to control that specific piece of install behavior.

Silent Install

Let's start with a basic silent install. Everything can be controlled through the command line options, but the switches used depend on which executable you run.

For now, test install procedures using a Windows command prompt. Don't get Smart Upgrade or SUrunAs involved until the install behaves as desired from a command prompt. Test using a Windows account with local administrator privileges.

Working with the webkit, the basic silent install command line would be ...

c1sp4en.exe -d -s -a /s /v"/qb+!"

(The "-d" switch isn't required for silent install, it cleans up the temp files afterward.)

This is fine for the simplest install cases, but later on we will need to change the contents of the install package which means we need to unpack the webkit into a folder. When we run the install we will execute setup.exe.

The command line for setup.exe is ...

setup.exe /s /v"/qb+!"

This will show a progress bar and present an "OK" dialog box when installation is complete. For a completely silent install, use "/qn" instead of "/qb+!".

Note that the initial Smart Upgrade dialogs which warn the user that the client will be shut down cannot  be suppressed. The user might need to save data before the client shuts down for Smart Upgrade and needs a warning.

Sametime and Symphony

These features are provisioned, they are built from plugins and installed by the new 8.x provisioning process so they cannot be controlled via InstallShield Tuner. To force installation of these features add SELECTINSTALLFEATURES to the command line.

Sametime only:

setup.exe /s /v"SELECTINSTALLFEATURES=SametimeUI /qb+!"

Just Symphony:

setup.exe /s /v"SELECTINSTALLFEATURES=Editors /qb+!"

Sametime and Symphony:

setup.exe /s /v"SELECTINSTALLFEATURES=SametimeUI,Editors /qb+!"

You could modify install.xml but those settings will only apply to new installations, not upgrades. In most cases SELECTINSTALLFEATURES is easier and works in all cases.

Use plugin_customization.ini to force some of the configurable Sametime parameters at install-time. The file is under the deploy folder in the installation package.

NOTE: Starting in Domino 8.0.2 the Sametime community and Single Sign-On options can be set via policy instead, you don't need to modify plugin_customization.ini for those preferences.

Add one or more of the following lines to set the default values of the Sametime preferences at install time.


com.ibm.collaboration.realtime.community/host=mySametime.acme.com
com.ibm.collaboration.realtime.community/port=1533
com.ibm.collaboration.realtime.community/loginByToken=true
com.ibm.collaboration.realtime.community/loginAtStartup=true
com.ibm.collaboration.realtime.login/autologin=true

Any parameter you do not include in plugin_customization.ini will get the default value. Only add one of the lines above if you want to change the value pushed to all clients during the install or upgrade.

Multiuser Install

If this is a multiuser install of the provisioned, Standard configuration client, you must add SETMULTIUSER=1 to the command line.

setup.exe /s /v"SETMULTIUSER=1 SELECTINSTALLFEATURES=SametimeUI,Editors /qb+!"

The text above is from TN 1375554