Installer - Available Actions

     


 Category: Control
 
 Change cancel button state
     
Changes the visibility and the enabled state of the cancel button. This action works in GUI mode as well as in unattended mode when the -splash option has been passed on the command line and the simple unattended progress dialog with a cancel button is shown.
Applies to: Installation, Uninstallation
Properties:
  • Button state
    The new button state for the cancel button.
 Run script
     
Runs a custom script. The script must return a boolean value. If it returns false, the installation will be canceled.
Applies to: Installation, Uninstallation
Properties:
  • Script [General]
    The script that will be executed. The script must return a boolean value. If it returns false, the installation will be canceled.
  • Optional Rollback Script [General]
    The script that will be executed in case of a rollback. The return type is void.
 Set a variable
     
Sets a variable by running a custom script. The script can return any java.lang.Object.
Applies to: Installation, Uninstallation
Properties:
  • Script [General]
    The script that will be executed. The script can return any java.lang.Object.
  • Variable name [General]
    The name of the variable that will be set. Enter the variable without the installer prefix and the percent signs.
  • Only if undefined [General]
    The variable will only be set if it was previously undefined. This is useful for variables that your user can pass via -V or -varfile at the command line.
  • Fail if value is null [General]
    If selected, the action will fail if a null value is returned from the script.
  • Register for response file [General]
    If selected, the variable will be saved to the response file .install4j/response.varfile that is created automatically when the installer exits.This is equivalent to calling context.registerResponseFileVariable(variableName) in a script.

    If the variable is present in the response file, the "Load response file" action in the startup node of the uninstaller will make this variable available in the uninstaller.

 Set messages
     
Sets the messages in the progress interface.
Applies to: Installation, Uninstallation
Properties:
  • Use status [General]
    If the status message should be set.
  • Status message
    The status message.

    Note: This property is only visible if "Use status" is selected.

  • Use detail [General]
    If the detail message should be set.
  • Detail message
    The detail message.

    Note: This property is only visible if "Use detail" is selected.

 Set the progress bar
     
Change the value of the progress bar or set it to indeterminate mode.
Applies to: Installation, Uninstallation
Properties:
  • Type of change
    Change the progress bar either to a percentage value, add progress, set it to indeterminate mode, start a timer, or return from indeterminate mode and show the last percentage value.
  • Percent value
    The progress value from 0 to 100. This property is only used when a percentage value is set or added.

    Note: This property is only visible if "Type of change" is set to "Set percentage value".

  • Timer period
    The time in milliseconds for one percent. This property is only used when the timer is started.

    Note: This property is only visible if "Type of change" is set to "Start a timer".

  • Timer maximum value
    The maximum progress value to be set by the timer. This property is only used when the timer is started.

    Note: This property is only visible if "Type of change" is set to "Start a timer".

 Sleep
     
Sleep a specified number of milliseconds. This is useful to ensure that a progress screen is displayed for at least a certain period of time.
Applies to: Installation, Uninstallation
Properties:
  • Sleep time
    The sleep time in milliseconds.
 Wait for HTTP port
     
Wait until an HTTP port becomes available. This is useful if you start a server, for example with a "Start a service" action, and need to wait until the server is operational before proceeding with the installation.
Applies to: Installation, Uninstallation
Properties:
  • Host name
    The host to which the URL connection should be made. By default this is set to "localhost" which checks on the computer that the installer is running on.
  • Port
    The port that should be checked. The default HTTP port is 80.
  • File part of URL
    An optional file part for the URL that should be checked. For example, if you enter "myPath", and the host name is "localhost" with port 80, the action will check http://localhost:80/myPath.
  • Timeout
    The timeout in seconds. After this timeout, the action will give up waiting for the HTTP port and fail. A timeout of 0 or a negative value means that the action will wait indefinitely for the HTTP port.
  • Accept all response codes
    If selected, all response code returned by the HTTP server will by accepted for the action to succeed. Otherwise, the action will continue to wait for the response code 200 (HTTP_OK). If the
  • Set indeterminate progress
    If selected, the progress bar will be set to indeterminate mode while the action is running. Note that this only has an effect if a progress bar is available on the current screen.
 Category: Desktop integration
 
 Add a desktop link
     
Create a link on the desktop to an installed executable or file. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Target file
    The installed file or executable for which a link will be created on the desktop
  • Name
    The name of the desktop icon
  • Arguments
    Optional arguments to the executable for Windows and Unix.
  • Target is Single Bundle [Mac OS X]
    If selected and the media set is a single bundle installer, the desktop icon will point to the bundle instead.
  • Create for all users [Windows]
    If the desktop link should be created for all users. If unselected, the link will be created for the current user only. If a "Create program group" screen is present, the "Create shortcuts for all users" check box will override this property.
  • Icon file [Windows]
    An optional different icon (*.ico) for the link on Windows.
  • Tooltip description [Windows]
    An optional description for Windows that will be displayed in the tooltip.
  • Start in [Windows]
    An optional working directory for the started executable.
 Add a startup executable on Windows and OS X
     
Add an installed executable to the startup folder on Windows or to the login items on OS X so that it will be started automatically when the user logs in. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Startup executable
    The executable that should be started when the user logs in
  • Set the hide flag [Mac OS X]
    If the hide flag should be set for the login item.
  • Entry name [Windows]
    The name of the entry in the startup folder
  • Create for all users [Windows]
    If the startup item should be created for all users. If unselected, the link will be created for the current user only.
 Add an executable to the dock
     
Add an installed executable to the dock on OS X. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Executable
    The executable that should be added to the dock.
 Create a Windows URL link
     
Create a URL link on Windows. This is a special text file with a .url link that is supported by the Windows desktop, start menu and explorer. To create links in the start menu, the "Create program group" action can be used as well. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • URL
    The URL that should be linked to. If no protocol is given, http:// is assumed.
  • Target file
    The path of the URL link, including the name of the link, but without the .url extension. To create a link on the desktop, prefix with ${installer:sys.desktopDir}
  • Icon file
    An optional icon file (*.ico) for the URL link. If empty, the default icon will be used.
  • Use favicon
    If the favicon file of the URL domain should be used. This only works if the icon has been cached by Internet Explorer.
 Create a file association
     
Create an association between a file extension and a launcher, so that the launcher is invoked when the user double-clicks a file with the selected extension.

On Windows, if the application has not yet been started, the arguments to the main method will contain the file name. Subsequent invocations and all invocations on Mac OS X can be intercepted with the com.install4j.api.launcher.StartupNotification class. Only effective on Windows and Mac OS X. This action will be automatically reverted by the 'Uninstall files' action.

Applies to: Installation
Properties:
  • File extension [General]
    The file extension for which the file association should be created. Must not include the leading dot.
  • Description [General]
    A description that is presented to the user as the text next to the corresponding checkbox in the "File associations" screen.
  • Launcher [General]
    The launcher that will be invoked when the file association is invoked by the user.
  • Selected [General]
    If the file association is selected in the "File associations" screen.
  • Execute on Mac OS X [Mac OS X]
    If the file association should be performed on Mac OS X.
  • Icon file for Mac OS X [Mac OS X]
    An optional icon file (*.icns) for the file association on Mac OS X. If empty, a default icon will be used.
  • Role [Mac OS X]
    The role the application can take for this file type.
  • Restart Finder [Mac OS X]
    If true the Finder should be restarted at the end of the installation. This might be necessary for the icon (and sometimes the association itself) to be picked up immediately. Note that users might find this restart disruptive. Additionally, if you launch an application at the end of the installation, it can be hidden by Finder windows.
  • Execute on Windows [Windows]
    If the file association should be performed on Windows.
  • Icon file for Windows [Windows]
    An optional icon file (*.ico) for the file association on Windows. If empty, a default icon will be used.
  • Additional parameters [Windows]
    Optional additional parameters that will be passed to the executable in front of the file to be opened.
 Create a quick launch icon
     
Create a link in the quick launch section of the Windows task bar to an installed executable or file. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Target file
    The installed file or executable for which a link will be created on the quick launch bar
  • Description
    The description that will be displayed in the tool tip
  • Icon file
    An optional icon file (*.ico) for the quick launch link. If empty, the default icon will be used.
  • Arguments
    Optional arguments that should be passed to the executable when started with the quick launch link.
 Create program group
     
Create standard program group entries on Windows and freedesktop.org compatible UNIX desktops. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Add default launcher links
    If generated launchers are placed into the program group automatically with their default menu integration properties. You can rename and move the default menu integrations in the program group entries tree. If you delete them, the default menu integration can be enabled again on the "Executable info->Menu integration" step of the launcher wizard.
  • Program group entries

    On Windows, the entries in the program group tree will be created in the start menu by the installer.

    The control buttons allow you to modify the contents of the list of program group entries. You can add new sub-folders and new file links.In the edit dialog, you have to fill in the display name of the program group entry.as wellas the target file for the of the program group link. This has to be a file or directory relative to the distribution root directory. Please note that if you select a directory as the target, it will not "fly out" in the program group, but a separate explorer window will be opened if the user clicks on it. To display all files in a directory, please add all of them as separate program group entries.

    Optionally, you can specify an icon that is used for this program group entry. The icon file must point to an *.ico file. If the file name is relative, it is interpreted as relative to the project file. If you do not specify an icon, the default icon is determined by the system.

  • Create symlinks [Unix]
    If symbolic links for all relevant launchers (those with "menu integration" enabled) should be created on UNIX.
  • Directory for links
    The default value for the directory in which links for all relevant launchers (those with "menu integration" enabled) will be created on UNIX.

    Note: This property is only visible if "Create symlinks" is selected.

  • Fail if symlinks are not created
    If selected, the action will fail if the symlinks cannot be created. Usually this is due to missing write permissions which is a common condition, so that the action does not fail by default.

    Note: This property is only visible if "Create symlinks" is selected.

  • Create menu entries [Unix]
    If menu entries should be created on freedesktop.org (KDE, GNOME) systems.
  • Application categories
    The freedesktop.org (KDE, GNOME) application categories used to determine the best place in the applications menu. Multiple categories can be separated by semicolons.

    Note: This property is only visible if "Create menu entries" is selected.

  • Program group name [Windows]
    The default value for the program group where the links will be created. If you leave this property empty, the links will be created at the top level.
  • Create for all users [Windows]
    If the program group is created for all users or only for the current user. If the sys.programGroupAllUsers is set (typically by the "Create program group" screen), the variable value will override this property.
  • Add uninstaller [Windows]
    If the uninstaller should be added to the program group.
  • Uninstaller menu name
    The name in the program group that will be used for the uninstaller.

    Note: This property is only visible if "Add uninstaller" is selected.

 Create start menu entry
     
Create a single start menu entry on Windows and Unix. For creating multiple program group entries, please see the "Create program group" action. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Entry name
    The entry name in the start menu. On Windows, the name can contain sub-folders with backslashes.
  • Target file
    The installed file or executable for which a start menu entry will be created
  • Arguments
    Optional arguments that should be passed to the executable when started with this entry.
  • Application categories [Unix]
    The freedesktop.org (KDE, GNOME) application categories used to determine the best place in the applications menu. Multiple categories can be separated by semicolons.
  • Icon file [Windows]
    An optional icon file (*.ico) for the entry. If empty, the default icon will be used.
  • Create for all users [Windows]
    If the program group is created for all users or only for the current user.
  • Program group name [Windows]
    The default value for the program group where the link will be created. If you leave this property empty, the link will be created at the top level.
  • Start in [Windows]
    An optional working directory for the started executable.
 Register Add/Remove item
     
Register an Add/Remove item in the Windows software registry. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Item name
    The name of the item that is displayed in the Windows software registry.
  • Icon
    An optional icon file (*.ico).
 Category: File operations
 
 Add Windows file rights
     
Adds access rights to files and directories on Windows.

If a helper process with elevated privileges has been created by the "Request privileges" action, this action is pushed to the helper process. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation, Uninstallation
Properties:
  • Files and directories
    The files and directories whose rights should be modified. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime. The rights for a directory will be inherited by all subdirectories and their contained files.
  • Trustee [Rights]
    The trustee for which the access right should be granted.
  • SID or Account Name
    The SID in String form or the account name for which the access right should be granted.

    Note: This property is only visible if "Trustee" is set to "SID or Account Name".

  • Read [Rights]
    The right to read the object.
  • Write [Rights]
    The right to write to the object.
  • Execute [Rights]
    The right to execute the object.
  • All [Rights]
    All available rights.
 Copy files and directories
     
Copy files and directories. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation, Uninstallation
Properties:
  • Destination directory
    The destination directory. If you have selected a single source file, this can also be a file rather than a directory. The destination directory will not be created, it must exist before this action is executed, otherwise it will be treated as a destination file.
  • Source files or directories
    The files and directories to be copied. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Show progress
    If selected, and a progress bar is available on the current screen, the action will show its progress in the progress bar.
  • Show file names
    If selected, the names of the files that are processed will be shown during the installation.

    Note: This property is only visible if "Show progress" is selected.

  • Overwrite mode
    How to handle an existing destination file.
  • Uninstall mode
    The mode how the uninstaller should handle the files created with this action.
  • Access mode [Unix]
    The UNIX access mode for files.
  • Directory access mode [Unix]
    The UNIX access mode for directories.
  • Shared file [Windows]
    If created files should be registered as a shared files.
  • Delay if necessary [Windows]
    If selected and a destination file cannot be replaced, the operation will be scheduled for the next reboot. The context method isRebootRequired() will return true in this case.
  • Trigger reboot if required [Windows]
    If selected and the operation is delayed until reboot, the user will be asked for a reboot automatically at the end of installation.
 Create a symbolic link
     
Creates a symbolic link. This action has no effect on Windows.
Applies to: Installation, Uninstallation
Properties:
  • File
    The file or directory that the symbolic link should point to.
  • Link file
    The link file that should be created. Relative files will be resolved relative to the installation directory.
  • Remove on uninstall
    If the link should be deleted by the 'Uninstall files' action in the uninstaller.
 Delete files and directories
     
Deletes files and directory. Directories can be deleted recursively.
Applies to: Installation, Uninstallation
Properties:
  • Files and directories
    The files and directories to be deleted. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Recursive
    If selected, the operation will be performed recursively on directories.
  • Backup for rollback
    If selected, a backup of the files to be deleted will be made and restored in case of rollback.
 Move files and directories
     
Moves files and directories. The newly created files are subject to removal by the 'Uninstall files' action.
Applies to: Installation, Uninstallation
Properties:
  • Destination directory
    The destination directory. If you have selected a single source file, this can also be a file rather than a directory. The destination directory will not be created, it must exist before this action is executed, otherwise it will be treated as a destination file.
  • Source files or directories
    The files and directories to be moved. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Show progress
    If selected, and a progress bar is available on the current screen, the action will show its progress in the progress bar.
  • Show file names
    If selected, the names of the files that are processed will be shown during the installation.

    Note: This property is only visible if "Show progress" is selected.

  • Overwrite mode
    How to handle an existing destination file.
  • Uninstall mode
    The mode how the uninstaller should handle the files created with this action.
  • Access mode [Unix]
    The UNIX access mode for files.
  • Directory access mode [Unix]
    The UNIX access mode for directories.
  • Shared file [Windows]
    If created files should be registered as a shared files.
  • Delay if necessary [Windows]
    If selected and a destination file cannot be replaced, the operation will be scheduled for the next reboot. The context method isRebootRequired() will return true in this case.
  • Trigger reboot if required [Windows]
    If selected and the operation is delayed until reboot, the user will be asked for a reboot automatically at the end of installation.
 Set the UNIX access mode of files and directories
     
Sets the UNIX access mode of files and directories. This action has no effect on Windows.
Applies to: Installation, Uninstallation
Properties:
  • Files and directories
    The files and directories that the access mode should be set for. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Recursive
    If selected, the operation will be performed recursively on directories.
  • Mode
    The mode to be set. This can be any string that can be used with chmod.
 Set the modification time of files
     
Sets the modification time of files.
Applies to: Installation, Uninstallation
Properties:
  • Files and directories
    The files and directories that the modification time should be set for. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Recursive
    If selected, the operation will be performed recursively on directories.
  • Time
    The new modification time.
 Set the owner of files and directories
     
Sets the owner and optionally the group of files and directories. This action has no effect on Windows.
Applies to: Installation, Uninstallation
Properties:
  • Files and directories
    The files and directories that the owner should be set for. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Recursive
    If selected, the operation will be performed recursively on directories.
  • Owner
    The owner to be set. If you want to set the group, too, please add it with a colon (example: user:group).
 Category: Final options
 
 Execute launcher
     
Execute an installed launcher and return immediately. This action is intended to be placed on the "Finish" screen. A confirmation can be added automatically to the "Finish" screen.

If the main installation process has been elevated by the "Request privileges" action, this action is pushed to the original process with limited rights. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation
Properties:
  • Launcher
    The launcher that will be executed. Service launchers are not shown.
  • Arguments
    The arguments passed to the launcher. Please note that in the property sheet, arguments have to be separated by semicolons (;) and in the edit dialog each argument starts on a new line. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Arguments that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate arguments, this allows you to build a variable length list of arguments at runtime.
 Reboot computer
     
Reboot the computer on Microsoft Windows. This action will trigger a reboot that takes place at the end of installation or uninstallation. By default, the user will be asked whether to reboot or not.
Applies to: Installation, Uninstallation
Properties:
  • Ask user
    Ask the user whether the reboot should be performed or not.
 Show PDF
     
Displays a PDF in a cross-platform viewer. A separate modal window will open.
Applies to: Installation
Properties:
  • PDF file
    The PDF file to display in a separate modal window.
  • Dialog title
    Text that shows on the PDF Viewer modal dialog window
 Show URL
     
Show a URL in the default browser. This action is intended to be placed on the "Finish" or the "Uninstallation success" screen.

If the main installation process has been elevated by the "Request privileges" action, this action is pushed to the original process with limited rights. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation, Uninstallation
Properties:
  • URL
    The URL that will be shown.
 Show file
     
Show a file with the associated application. Usually, a text file or an HTML file is appropriate. This action is intended to be placed on the "Finish" screen. A confirmation can be added automatically to the "Finish" screen.

If the main installation process has been elevated by the "Request privileges" action, this action is pushed to the original process with limited rights. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation
Properties:
  • File
    The file that will be shown.
 Category: Java preference store
 
 Delete a node or key in the Java preference store
     
Delete an entire package node or a key-value pair in the Java preference store.
Applies to: Installation, Uninstallation
Properties:
  • Package name
    The name of the package node in the preference store that should be deleted or contains the key-value pair to be deleted. The action does not return an error if this package node does not exist.
  • Key
    The key that should be deleted. If you leave this empty, the entire package node will be deleted instead. The action does not return an error if this key does not exist.
  • Preference root
    If you want to delete the node or key-value pair for the current user, all users, or both.
  • Only if empty
    If a node should only be deleted when it contains no sub-nodes or keys.
 Read a key from the Java preference store
     
Read the value of a key from the Java preference store and save it to an installer variable. Only string values can be read.
Applies to: Installation, Uninstallation
Properties:
  • Package name
    The name of the package node in the preference store where the key is located.
  • Key
    The key whose value should be read.
  • Use a default value
    If selected, a default value will be saved to the variable if the key cannot be found in the preference store. Otherwise a missing key will result in the failure of the action and the variable will not be set.
  • Default value
    The default value that will be used if the key cannot be found in the preference store.

    Note: This property is only visible if "Use a default value" is selected.

  • Preference root
    If you want to read the value of the key for the current user, all users, or first read the settings for all users and then override with the user-specific settings.
  • Variable name
    The name of the variable that will be set with the string value. Enter the variable without the installer prefix and the percent signs. If the key cannot be found in the preference store, the variable value will not be set.
 Set a key in the Java preference store
     
Set a key-value pair in the Java preference store. The package node is created if necessary. This is the most convenient way to communicate settings to related installers. Only string values can be set.
Applies to: Installation, Uninstallation
Properties:
  • Package name
    The name of the package node in the preference store where the key-value pair should be set.
  • Key
    The key for which a value should be set.
  • Value
    The string value that should be set for the key.
  • Preference root
    If you want to set the key for the current user only or for all users. Due to access rights it can happen that the system preference registry is not writable, in that case a fallback to the user specific registry can be tried.
 Category: Miscellaneous
 
 Add VM options
     
Adds VM options for a launcher by modifying or creating a .vmoptions file or by changing the Info.plist file. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Launcher
    The launcher that the VM options should be added for.
  • VM options
    The unquoted options that should be added. Note that system property definitions must be prefixed with -D just as on the command line, e.g. -Dkey=value. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. VM options that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate VM options, this allows you to build a variable length list of VM options at runtime.
 Check for running processes on Windows
     
Check for installed launchers and additional running processes on Windows.
Applies to: Installation, Uninstallation
Properties:
  • Include launchers
    If selected, the operation will check for running launchers in the current installation directory.
  • Additional executables
    The additional executables that should be checked. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Additional executables that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate additional executables, this allows you to build a variable length list of additional executables at runtime. From relative files, only the file name is used for comparison. This enables checking for executables with an unknown location. To reference executables relative to your installation directory, please prefix them with ${installer:sys.installationDir}/. This is an optional property.
  • Close strategy
    The strategy used when processes are running.
  • Ignore button
    Add an ignore button to the dialog. The action will return successfully if the user clicks this button.
  • Time out for close
    The time out for the soft close strategy in milliseconds.
  • Message
    The message to be displayed at the top of the dialog.
 Modify an environment variable on Windows
     
Sets, appends to, or prepends to an environment variable on Windows. This action can be automatically reverted by the 'Uninstall files' action.
Applies to: Installation, Uninstallation
Properties:
  • Modification type
    Modification type
  • Variable name
    The name of the variable that should be modified.
  • Value
    The value to be set, appended or prepended.
  • User specific
    If the variable is user specific or system wide. This has no effect on Windows 9x.
  • Revert on uninstallation [Uninstallation]
    Revert the change automatically on uninstallation if this action is used for an installer. This has no effect on Windows 9x.
  • Only if not modified
    Revert the change only if the environment variable hss not been modified in the mean time. This is mainly useful for the 'set' modification type.

    Note: This property is only visible if "Revert on uninstallation" is selected.

 Modify classpath
     
Changes the classpath of a launcher by modifying or creating a .vmoptions file or by changing the Info.plist file. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Launcher
    The launcher that the classpath should be changed for.
  • Classpath entries
    The classpath entries. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Entries that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate entries, this allows you to build a variable length list of entries at runtime.
  • Modification type
    Modification type
 Request privileges
     
Requests configurable administrator privileges. On Windows Vista and higher and on OS X, the installer will be restarted with the requested privileges or a helper process will be created that can perform certain actions in a privileged context. When you restart the installer, you should not install files before this action.

Please see the help topic on "Elevation Of Privileges" for a detailed discussion of this action.

Applies to: Installation, Uninstallation
Properties:
  • Try to obtain root privileges if admin user [Mac OS X]
    If set and the user is an admin user, the action will try to start a new process with root privileges. The user will have to enter his password.
  • Try to obtain root privileges if normal user [Mac OS X]
    If set and the user is a non-admin user, the action will try to start a new process with root privileges. The user will have to enter the password of an admin account.
  • Obtain privileges for [Mac OS X]
    If an elevation should be performed, either the main installation process will be restarted and all actions will run elevated or an elevated helper process will be started that can execute particular actions (install service etc.) elevated in the further installation process.
  • Show failure if requested privileges cannot be obtained [Mac OS X]
    If set and the privileges required above could not be obtained a failure message will be shown and the installation will be canceled. This property overrides the "Failure strategy" property of the action. A separate property is necessary since the behavior can be configured differently for Windows, Mac OS X and Unix.
  • Show failure if current user is not root [Unix]
    If set and the current user is not root a failure message will be shown and the installation will be canceled. This property overrides the "Failure strategy" property of the action. A separate property is necessary since the behavior can be configured differently for Windows, Mac OS X and Unix.
  • Try to obtain full privileges if admin user [Windows]
    If set and the user is an admin user with limited privileges on Vista and higher, the action will try to start a new process with full privileges.
  • Try to obtain full privileges if normal user [Windows]
    If set and the user is a non-admin user, the action will either try to start a new process with full privileges on Vista and higher or fail on previous versions of Windows.
  • Obtain privileges for [Windows]
    If an elevation should be performed, either the main installation process will be restarted and all actions will run elevated or an elevated helper process will be started that can execute particular actions (install service etc.) elevated in the further installation process.
  • Show failure if requested privileges cannot be obtained [Windows]
    If set and the privileges required above could not be obtained a failure message will be shown and the installation will be canceled. This property overrides the "Failure strategy" property of the action. A separate property is necessary since the behavior can be configured differently for Windows, Mac OS X and Unix.
 Run executable or batch file
     
Runs an executable or a Windows batch file. The action can optionally wait for termination of the executable.
Applies to: Installation, Uninstallation
Properties:
  • Executable
    The file that should be executed. Please do not add arguments here, there is a separate "Arguments" property.
  • Working directory
    The working directory for the execution.
  • Arguments
    The arguments passed to the executable. Please note that in the property sheet, arguments have to be separated by semicolons (;) and in the edit dialog each argument starts on a new line. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Arguments that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate arguments, this allows you to build a variable length list of arguments at runtime.
  • Wait for termination
    If the action should wait for termination of the process and check if the return value is 0.
  • Variable name for return code
    If set, the return code will be saved to this installer variable. The type of the variable will be java.lang.Integer. Under Windows, this variable will always be equal to 0 if the "Show console window" option below is selected.

    Note: This property is only visible if "Wait for termination" is selected.

  • Log arguments
    If the arguments should be written into the log file or not. Disabled by default due to security reasons.
  • Execution account
    On Windows Vista or higher and Mac OS X, you can specify the type of account the process should use. You have to add a 'Request privileges' before this action if you want it to run with admin rights.

    Please see the help topic on "Elevation Of Privileges" for more information.

  • Include parent environment variables [Environment Variables]
    If selected, the environment variables of the parent process (the installer) will be set. Otherwise, only the environment variables in the "Specific environment variables" will be set. This option is ignored on OS X.
  • Specific environment variables [Environment Variables]
    Specify additional or modified environment variables that should be set for the executed process. Use the button to the right side to open a dialog for easy entry or enter a list of definitions separated by semicolons like VAR1=value1;VAR2=value2. Use previous values with the syntax "PATH=${PATH};additional". In this case the entire entry has to be quoted, otherwise the semicolon would have been a separator. Do not quote semicolons in the dialog. Variable definitions that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate variable definitions, this allows you to build a variable length list of variable definitions at runtime.
  • Redirection file for stdout [Redirection]
    A file to which the stdout output of the executed process is saved. If empty, the stdout output will be discarded. If you specify /dev/stdout, the output will be printed to the default stdout stream of the installer application. Relative paths are relative to the working directory of the installer application. In order to use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt.
  • Redirection file for stderr [Redirection]
    A file to which the stderr output of the executed process is saved. If empty, the stderr output will be discarded. If you specify /dev/stderr, the output will be printed to the default stderr stream of the installer application. Relative paths are relative to the working directory of the installer application. In order to use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt.
  • Redirection file for stdin [Redirection]
    A file which should be fed to the input stream of the executed process. If empty, the stdin input will be empty. If you specify /dev/stdin, the input from the default stdin stream of the installer application will be used. Relative paths are relative to the working directory of the installer application. In order to use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt.
  • Fail for redirection errors [Redirection]
    If selected, the action fails if the redirection files cannot be accessed. Otherwise, those errors are silently ignored.
  • Show console window [Windows]
    Show a console window with the console output of the executable. This makes only sense if a command line executable is called and has no effect on Windows 9x.
  • Keep console window
    If selected, the console window will not be closed when the executable has finished. The user has to close the console window manually. This can be useful for debugging purposes. If the "Wait for termination" property is selected, the action will not terminate until the user has closed the console window.

    Note: This property is only visible if "Show console window" is selected.

 Category: Persistence of installer variables
 
 Create a response file
     
Create a response file at an arbitrary location to save user input for subsequent installations. This file can be used with the -varfile command line option.
Applies to: Installation, Uninstallation
Properties:
  • File
    The response file that should be created. If it already exists, it will be overwritten.
  • Excluded variables
    The variable that should be excluded from the response file. If empty all variables will be used. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Entries that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate entries, this allows you to build a variable length list of entries at runtime.
 Load a response file
     
Load a response file that has previously been saved with the "Create a response file" action.
Applies to: Installation, Uninstallation
Properties:
  • File
    The response file that should be loaded. If empty, the action will try to load the automatically created response file named response.varfile that has been saved by a previous installer in the installation directory.
  • Excluded variables
    The variables in the response file that should be ignored. If empty, all variables will be loaded. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Entries that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate entries, this allows you to build a variable length list of entries at runtime.
 Load installer variables from the Java preference store
     
Load installer variables from the Java preference store that have been previously saved by the "Save installer variables to the Java preference store" action.
Applies to: Installation, Uninstallation
Properties:
  • Package name
    The name of the package node in the preference store where the installer variables should be loaded from. By default, this is set to the application ID.
  • Preference root
    If you want to load the installer variables for the current user, all users, or first read the settings for all users and then override with the user-specific settings.
 Save installer variables to the Java preference store
     
Save installer variables to the Java preference store. This can be used to communicate installer variables to the uninstaller or to installers with different application IDs.
Applies to: Installation, Uninstallation
Properties:
  • Package name
    The name of the package node in the preference store where the installer variables should be set. By default, this is set to the application ID.
  • Preference root
    If you want to save the installer variables for the current user only or for all users. Due to access rights it can happen that the system preference registry is not writable, in that case a fallback to the user specific registry can be tried.
  • Installer variable names
    A list of installer variable names. Just enter the names of the installer variables, not including the surrounding ${installer:...} syntax used for variable substitution in text fields. Variables with value null will be ignored. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Entries that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate entries, this allows you to build a variable length list of entries at runtime.
 Category: Services
 
 Install a service
     
Installs a service. On Windows, this is done by executing the service launcher with the appropriate arguments. On Unix, a link will be placed in /etc/init.d. On Mac OS, a LaunchDaemon will be created. This action will be automatically reverted by the 'Uninstall files' action.

If a helper process with elevated privileges has been created by the "Request privileges" action, this action is pushed to the helper process. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation
Properties:
  • Service [General]
    The service launcher that will be installed.
  • Executable
    The service executable.
  • Name
    The name of the service.
  • Auto Start [General]
    If the service should be started automatically at boot time.
  • Description [General]
    An optional description for the service.
  • Mac OS X Identifier [Mac OS X]
    The launch daemon identifier for OS X. Typically, this is something like com.mycorp.myService.
  • Account Name or SID
    The account name or a SID in String form.

    Note: This property is only visible if "Account" is set to "Other".

  • Password
    The password for the specified account.

    Note: This property is only visible if "Account" is set to "Other".

  • Windows Arguments [Windows]
    Optional arguments passed to the main function of the service executable.
  • Windows Dependencies [Windows]
    Optional dependencies for Windows. Specify as a comma-separated list of the names of the services that must be started before this service. You do not have to enter core OS services these services will always be initialized before your service is launched.
  • Windows Priority [Windows]
    The base priority class for the service. This only applies to services generated by install4j.
  • Account [Windows]
    The account the service should run under. Use Local System if you are not sure what you need.
  • Keep Current Account [Windows]
    If the service was already installed, use the currently specified account instead of the values above.
  • Restart on Failure [Windows]
    If the service should be automatically restarted if it doesn't exit with exit code 0 or if it crashes.
  • Interactive [Windows]
    If the service can interact with the desktop. Not recommended for Windows Vista and higher.
 Start a service
     
Starts a service by executing the service launcher with the appropriate arguments.

If a helper process with elevated privileges has been created by the "Request privileges" action, this action is pushed to the helper process. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation
Properties:
  • Service [General]
    The service launcher that will be started.
  • Executable
    The service executable.
  • Name
    The name of the service.
  • For "Auto start installations" only [General]
    If selected, the service will only be started when it is installed as an "Auto start" service on Windows and OS X. This is a property on the "Install a service" action.
 Stop a service
     
Stops a service by executing the service launcher with the appropriate arguments.

If a helper process with elevated privileges has been created by the "Request privileges" action, this action is pushed to the helper process. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation, Uninstallation
Properties:
  • Service [General]
    The service launcher that will be stopped.
  • Executable
    The service executable.
  • Name
    The name of the service.
 Category: Text files
 
 Fix line feeds
     
Changes the line feeds of text files to the platform specific type.
Applies to: Installation, Uninstallation
Properties:
  • Text files
    The text files that should be fixed. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Text files that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate text files, this allows you to build a variable length list of text files at runtime. You can add directories as well. In this case, all files in the selected directories that satisfy the "Suffixes" property will be fixed.
  • Suffixes
    The suffixes with a leading dot of the files to be fixed if the "File" property is a directory. If empty, all files will be used. The items in the list must be separated by semicolons. If you click on the edit button in the property editor, you can enter one item per line in a separate dialog. Suffixes that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate suffixes, this allows you to build a variable length list of suffixes at runtime.
  • Recursive
    If selected, the operation will be performed recursively on directories. If no selected, all files in directories will be fixed, but subdirectories will not be touched.
 Modify text files
     
Modify installed text files by replacing a search value in the selected files. This action does not read the entire file into memory and can work on arbitrarily large text files.
Applies to: Installation, Uninstallation
Properties:
  • Text files
    The text files that should be modified. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Text files that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate text files, this allows you to build a variable length list of text files at runtime.
  • Search value
    The value that should be searched
  • Replace value
    The value that should be used instead
  • Log replacement
    If the replacement text should be written into the log file or not. If the modified file has different security settings than the log file, you might want to disable this property for security reasons.
  • Fail if no replacement occurred
    If selected, the action will fail if no replacement was performed by the action. Note that you have to set the error message property in order to display the error to the user.
  • Escape for property file
    If set, the replaced values will be escaped for use in a Java property file.
  • Encoding
    The encoding of the file. If you leave this empty the system default will be used. Common encodings are UTF-8, UTF-16, ISO-8859-1.
 Modify text files with regular expressions
     
Modify installed text files by applying a regular expression.
Applies to: Installation, Uninstallation
Properties:
  • Text files
    The text files that should be modified. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Text files that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate text files, this allows you to build a variable length list of text files at runtime.
  • Match expression
    The match expression, which is applied to the entire contents of the file. If you wish to use the characters ^ and $ for matching line start and line end, please prefix the expression with (?m). This switches on multi-line mode. For case-insensitive expressions, prefix with (?i).
  • Replacement
    The replacement.
  • Replace all
    If all occurrences should be replaced or only the first one.
  • Quote variables
    If values of installer variables in the match and replacement expressions should be quoted. This means that the characters of replaced installer variables will be treated literally instead of modifying the search or replace expressions with special characters such as \ or $.
  • Log replacement
    If the replacement text should be written into the log file or not. If the modified file has different security settings than the log file, you might want to disable this property for security reasons.
  • Fail if no replacement occurred
    If selected, the action will fail if no replacement was performed by the action. Note that you have to set the error message property in order to display the error to the user.
  • Escape for property file
    If set, the replaced values will be escaped for use in a Java property file.
  • Encoding
    The encoding of the file. If you leave this empty the system default will be used. Common encodings are UTF-8, UTF-16, ISO-8859-1.
 Read text from file
     
Read the content of a text file and save it to an installer variable. The variable value will be of type String.
Applies to: Installation, Uninstallation
Properties:
  • File
    The file from which the text should be read. If the file does not exist, the variable value will not be set.
  • File encoding
    The encoding of the text file. If empty, the native encoding of the operating system will be used.
  • Variable name
    The name of the variable whose value will be set to the text content of the file. If the file cannot be found, the variable value will not be set.
 Replace installer variables in text files
     
Modify installed text files by replacing all occurrences of installer variables of the form ${installer:myVariable} with their current values. The action also replaces i18n variables like ${i18n;myKey} and compiler variables like ${compiler:myCompilerVariable}
Applies to: Installation, Uninstallation
Properties:
  • Text files
    The text files that should be modified. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Text files that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate text files, this allows you to build a variable length list of text files at runtime.
  • Ignore missing variables
    If selected, all missing occurrences of variables will be left as they are. If unselected, a missing variable will be a fatal error leading to the termination of the installer.
  • Fail if no replacement occurred
    If selected, the action will fail if no replacement was performed by the action. Note that you have to set the error message property in order to display the error to the user.
  • Escape for property file
    If set, the replaced values will be escaped for use in a Java property file.
  • Encoding
    The encoding of the file. If you leave this empty the system default will be used. Common encodings are UTF-8, UTF-16, ISO-8859-1.
 Write text to a file
     
Write text to a new file or append text to an existing file.
Applies to: Installation, Uninstallation
Properties:
  • File
    The file that the text should be appended to. If it doesn't exist it will be created.
  • Text
    The text that should be appended.
  • Encoding
    The encoding of the file. If you leave this empty the system default will be used.
  • Escaped text
    If selected, escape sequences like \n,\t or \u1234 in the text property will be replaced.
  • Append
    If selected, and the file exists, the text will be appended to the existing file. If the file does not exist, it will be created in any case.
  • Log text
    If the text should be written into the log file or not. If the written file has different security settings than the log file, you might want to disable this property for security reasons.
 Category: Update
 
 Check for update
     
Load the update descriptor from the a URL and save it to the a variable. If successful, the variable will contain an instance of com.install4j.api.UpdateDescriptor
Applies to: Installation, Uninstallation
Properties:
  • Update descriptor URL
    The URL from which the update descriptor for this project can be downloaded. The update descriptor file is automatically created when compiling the project and can be found in the media output directory. The URL should start with http://, for testing purposes, you can also use a file URL like file:/c:/test/updates.xml.
  • Variable
    The installer variable to which an instance of class com.install4j.api.UpdateDescriptor will be saved if the action is successful.
  • Show error message [Error Handling]
    Show a default error message if the download fails.
  • Ask for proxy if necessary [Error Handling]
    At first, the connection is attempted with the proxy information that is set for the default browser. If that fails, and this property is selected, a proxy dialog will be shown where the user can configure the proxy that should be used to connect to the web server.
 Download file
     
Download a URL and save it to a file
Applies to: Installation, Uninstallation
Properties:
  • URL
    The URL from which the file should be downloaded. The URL must start with http://.
  • Target file
    The file to which the downloaded URL will be saved.
  • Retry if interrupted
    If selected, ask the user to retry if a successfully started download is interrupted.
  • Check for md5sums
    If selected, the action will try to download a file named md5sums from either the directory of the above URL or from the optional URL given below. If the download is successful and the file contains an entry for the target file name, it will be checked. If the MD5 checksums do not match and the "Silent failure" option is not selected, a dialog will be shown that offers the possibility to retry the download.
  • Optional md5sums URL
    An optional URL for the md5ums file. If specified, only this URL will be used.

    Note: This property is only visible if "Check for md5sums" is selected.

  • Silent failure
    If selected, the action will fail immediately if a mismatch in the MD5 checksums occurs. Otherwise the user will be presented with a dialog box that explains the failure and offers the possibility to retry the download.

    Note: This property is only visible if "Check for md5sums" is selected.

  • Show progress
    If selected, and a progress bar is available on the current screen, the action will show its progress in the progress bar.
  • Show file name
    If selected, the name of the downloaded file and the target directory will be displayed. This setting has no effect if "Show progress" is not selected.
  • Delete downloaded file on exit
    If selected, the downloaded file will be deleted when the installer application terminates.
  • Show error message [Error Handling]
    Show a default error message if the download fails.
  • Ask for proxy if necessary [Error Handling]
    At first, the connection is attempted with the proxy information that is set for the default browser. If that fails, and this property is selected, a proxy dialog will be shown where the user can configure the proxy that should be used to connect to the web server.
 Shut down calling launcher
     
Shut down the launcher that called this application if it was started with the com.install4j.api.launcher.ApplicationLauncher API.
Applies to: Installation, Uninstallation
Properties:
  • Wait
    If selected the action will wait for the calling launcher to exit.
  • Timeout
    The timeout in seconds this action will wait if the 'Wait' property is true. If set to 0 there will be no timeout.
 Category: Windows registry
 
 Add access rights for a key in the Windows registry
     
Add access rights for a key in the Windows registry.

If a helper process with elevated privileges has been created by the "Request privileges" action, this action is pushed to the helper process. Please see the help topic on "Elevation Of Privileges" for more information.

Applies to: Installation, Uninstallation
Properties:
  • Registry root
    The Windows registry root where the key is located.
  • Key name
    The name of the registry key without a leading backslash.
  • Trustee [Rights]
    The trustee for which the access right should be granted.
  • SID or Account Name
    The SID in String form or the account name for which the access right should be granted.

    Note: This property is only visible if "Trustee" is set to "SID or Account Name".

  • Read [Rights]
    The right to read the object.
  • Write [Rights]
    The right to write to the object.
  • Execute [Rights]
    The right to execute the object.
  • All [Rights]
    All available rights.
 Delete a key or value in the Windows registry
     
Delete a key or value in the Windows registry.
Applies to: Installation, Uninstallation
Properties:
  • Registry root
    The Windows registry root where the key or value should be deleted.
  • Key name
    The name of the registry key that should be deleted or contains the value to be deleted without a leading backslash.
  • Value name
    The name of the registry value that should be deleted. If you leave this empty, the key will be deleted instead.
  • Only if empty
    If a key should only be deleted when it contains no sub-keys or values.
 Read a value from the Windows registry
     
Read a value from the Windows registry and save it to an installer variable. The type of the value depends on the type in the registry, it will be an instance of one of the following classes: String, Integer, String[], byte[], WinRegistry.ExpandString.
Applies to: Installation, Uninstallation
Properties:
  • Registry root
    The Windows registry root where the key is located.
  • Key name
    The name of the registry key where the value is located without a leading backslash.
  • Value name
    The name of the registry value whose string content should be read.
  • Use a default value
    If selected, a default value will be saved to the variable if the key cannot be found in the registry. Otherwise a missing registry value will result in the failure of the action and the variable will not be set.
  • Default value
    The default value that will be used if the value cannot be found in the registry.

    Note: This property is only visible if "Use a default value" is selected.

  • Variable name
    The name of the variable that will be set with the value. Enter the variable without the installer prefix and the percent signs. If the value cannot be found in the registry, the variable value will not be set.
 Set a value in the Windows registry
     
Set a value in the Windows registry. This action can also create the appropriate key if necessary.
Applies to: Installation, Uninstallation
Properties:
  • Registry root
    The Windows registry root where the key should be created
  • Key name
    The name of the registry key that contains the value or that should be created without a leading backslash.
  • Value name
    The name of the registry value.
  • Value
    The value that should be written into the registry.
  • Create key
    If set the key will be created if it doesn't exist.
 Category: XML files
 
 Apply an XSLT transform
     
Transform an installed file by applying an XSLT stylesheet.
Applies to: Installation, Uninstallation
Properties:
  • Source file
    The source for the transformation. This can be the same file as the destination.
  • Destination file
    The output of the transformation. This can be the same file as the source.
  • Stylesheet
    The XSLT stylesheet to apply.
  • Download external entities [XML parser]
    If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case.
  • Validate XML file [XML parser]
    If selected, the XML parser will validate the document according to a associated DTD or XML schema. If the validation is unsuccessful, the action will fail.
 Read value from XML file
     
Read a string value from an XML file specified by an XPath expression and save the result to an installer variable.
Applies to: Installation, Uninstallation
Properties:
  • XML file
    The XML file that should be read. It will not be validated, and no external entities will be downloaded.
  • XPath expression
    The XPath expression to the DOM node whose string value should be read. Example for reading text from an attribute: /myRootNode/myChildNode/@myAttribute. Example for reading text from an element: /myRootNode/myChildNode/text()
  • Variable name
    The name of the variable that will be set with the string value. Enter the variable without the installer prefix and the percent signs. If the XPath expression cannot be found, the variable value will not be set.
 Replace text in XML files
     
Modify installed XML files by selecting nodes with an XPath expression and applying a regular expression on the selected values.
Applies to: Installation, Uninstallation
Properties:
  • XML files
    The XML files that should be modified. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. XML files that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate XML files, this allows you to build a variable length list of XML files at runtime.
  • XPath expression
    The XPath expression to selected DOM nodes that have a value (this includes attributes and text). Example for replacing text in an attribute: /myRootNode/myChildNode/@myAttribute. Example for replacing text in an element: /myRootNode/myChildNode/text(). If you want to match line breaks with the dot as well, prefix the regular expression with (?s). If you want the comparison to be case insensitive, prefix it with (?i).
  • Match expression
    The match expression.
  • Replacement
    The replacement.
  • Replace all
    If all occurrences should be replaced or only the first one.
  • Quote variables
    If values of installer variables in the match and replacement expressions should be quoted. This means that the characters of replaced installer variables will be treated literally instead of modifying the search or replace expressions with special characters such as \ or $.
  • Log replacement
    If the replacement text should be written into the log file or not. If the modified file has different security settings than the log file, you might want to disable this property for security reasons.
  • Download external entities [XML parser]
    If selected, a DTD referenced with an HTTP system ID will be downloaded as the document is parsed. The success of the action requires a direct internet connection in that case.
  • Validate XML file [XML parser]
    If selected, the XML parser will validate the document according to a associated DTD or XML schema. If the validation is unsuccessful, the action will fail.
 Category: ZIP files
 
 Create a ZIP file
     
Create a ZIP file from the specified source files and directories.
Applies to: Installation, Uninstallation
Properties:
  • ZIP file
    The ZIP file that should be created.
  • Source files or directories
    The files and directories to be zipped. Multiple files are separated by semicolons. Use the chooser button to the right side of the text field to display a dialog where you can conveniently choose files from the distribution tree. Files and directories that are installer variables with array values (e.g. String[], Object[] or File[]) are expanded as separate files and directories, this allows you to build a variable length list of files and directories at runtime.
  • File filter script
    The file filter script is invoked for each file that is about to be processed by this action. The script is not invoked for directories. You can return true if the file should be processed or false if it should be excluded from processing.
  • Directory filter script
    The directory filter script is invoked for each directory that is about to be processed by this action. The script is not invoked for files. You can return true if the directory should be processed or false if it should be excluded from processing.
  • Show progress
    If selected, and a progress bar is available on the current screen, the action will show its progress in the progress bar.
  • Show file names
    If selected, the names of the files that are processed will be shown during the installation.

    Note: This property is only visible if "Show progress" is selected.

  • Add top level directories
    If selected, all directories that you have added to the source files, will be added under the name of the directory. Otherwise, the contents of the directories will be added directly to the root of ZIP file.
 Extract a ZIP file
     
Extracts the content of a ZIP file to an arbitrary location.
Applies to: Installation, Uninstallation
Properties:
  • Zip file
    The zip file that contains the content to be installed.
  • File filter script
    The file filter script is invoked for each entry in the ZIP file that is about to be processed by this action. The script is invoked for both directories and files, which are passed as relative files. You can return true if the file or directory should be processed or false if it should be excluded from processing. If you leave the script empty, all files and directories are processed.

    Note that ZIP files have no hierarchical directory structure, so it is not guaranteed that you are passed directory entries before entries of contained files. This also means that by excluding a directory, you do not automatically exclude its contents, you have to check and reject each contained file as well.

  • Destination directory
    The destination directory. Relative directory information in the zip file will be added to this value. If the destination directory does not exist, it will be created.
  • Show progress
    If the action should show its progress with the progress bar and the detail message.
  • File access mode [Unix]
    The UNIX access mode of extracted files.
  • Dir access mode [Unix]
    The UNIX access mode of extracted directories.
 Install content of a ZIP file
     
Installs the content of an external ZIP file to an arbitrary location. This action will be automatically reverted by the 'Uninstall files' action.
Applies to: Installation
Properties:
  • Zip file
    The zip file that contains the content to be installed.
  • File filter script
    The file filter script is invoked for each entry in the ZIP file that is about to be processed by this action. The script is invoked for both directories and files, which are passed as relative files. You can return true if the file or directory should be processed or false if it should be excluded from processing. If you leave the script empty, all files and directories are processed.

    Note that ZIP files have no hierarchical directory structure, so it is not guaranteed that you are passed directory entries before entries of contained files. This also means that by excluding a directory, you do not automatically exclude its contents, you have to check and reject each contained file as well.

  • Destination directory
    The destination directory. Relative directory information in the zip file will be added to this value. If the destination directory does not exist, it will be created.
  • Show progress
    If the action should show its progress with the progress bar and the detail message.
  • Overwrite mode
    How to handle an existing destination file.
  • Uninstall mode
    The mode how the uninstaller should handle files created with this action.
  • File access mode [Unix]
    The UNIX access mode of installed files.
  • Dir access mode [Unix]
    The UNIX access mode of installed directories.
  • Shared file [Windows]
    If the file should be registered as a shared file.
  • Delay if necessary [Windows]
    If selected and a destination file cannot be replaced, the operation will be scheduled for the next reboot. The variable sys.rebootRequired will be set to Boolean.TRUE in this case.
  • Trigger reboot if required [Windows]
    If selected and an operation is delayed until reboot, the user will be asked for a reboot automatically at the end of installation.
 Download and install component
     
Download a specified downloadable component and install it. This action only works for installation components that have been marked as "downloadable" on the "Options" tab of the installation component configuration.

Note: The "Install Files" action already downloads and installs all selected downloadable installation components.This action is intended for scenarios where an installation component has to be downloaded after the "Install files" action has run. For example, you could use this in a custom installer application to install optional files.

Applies to: Installation
Properties:
  • Installation component
    The installation component to be downloaded. Only downloadable installation components are displayed
  • Show progress
    If selected, and a progress bar is available on the current screen, the action will show its progress in the progress bar.
  • Show file names
    If selected, the names of the files that are installed will be shown during the installation.
  • File filter [Handlers]
    Expression or script that is invoked for each file to decide whether to install the file or not.
  • Directory resolver [Handlers]
    Expression or script that resolves the actual installation directory separately for each installed file. Return null, if you would like to choose the standard installation directory for a file.
  • Delay if necessary [Windows]
    If selected and a destination file cannot be replaced, the operation will be scheduled for the next reboot. The context method isRebootRequired() will return true in this case.
  • Trigger reboot if required [Windows]
    If selected and an operation is delayed until reboot, the user will be asked for a reboot automatically at the end of installation.
 Install files
     
Install all files in the distribution tree that are contained in the selected installation components.
Applies to: Installation
Properties:
  • Validate application id
    Check if another application is installed in the selected directory or if the application is not the correct target for an add-on installer. If you have an "installation location" screen, you don't have to select this option.
  • Insufficient disk space warning
    Show a warning message if there is not sufficient disk space for the installation on the selected target drive.
  • Install runtime
    Create the installation directory and install the install4j runtime. If your installer just modifies some folders and does not need launchers, an uninstaller or custom installer applications, you can deselect this option and use other installation roots in the distribution tree to install files.
  • Update bundled JRE
    Update a bundled JRE if it already exists. If your application uses the JRE outside the generated launchers, an update of a bundled JRE might fail. In that case you can deselect this property to keep the old JRE and skip the update.
  • Save downloaded files
    If this property is set and the action downloads files it will try to place them next to the media file. In this case, the installer won't have to download the files again if it is invoked another time.
  • Show file names
    If selected, the names of the files that are installed will be shown during the installation.
  • File filter [Handlers]
    Expression or script that is invoked for each file to decide whether to install the file or not.
  • Directory resolver [Handlers]
    Expression or script that resolves the actual installation directory separately for each installed file. Return null, if you would like to choose the standard installation directory for a file.
  • Installation size calculator [Handlers]
    Expression or script that calculates a custom installation size in bytes. The default size in bytes is passed as a parameter.
  • Delay if necessary [Windows]
    If selected and a destination file cannot be replaced, the operation will be scheduled for the next reboot. The context method isRebootRequired() will return true in this case.
  • Trigger reboot if required [Windows]
    If selected and an operation is delayed until reboot, the user will be asked for a reboot automatically at the end of installation.
 Uninstall files
     
Uninstall all installed files.
Applies to: Uninstallation
 Uninstall previous installation
     
Uninstalls the previous installation of this application in the selected installation directory.
Applies to: Installation
Properties:
  • Installation directory
    The installation directory for which the uninstaller should be run. Leave empty for the current installation directory.
  • Only if the same application ID is found
    If selected, the action will only be performed if the application ID found in the installation directory is the same as that of the currently executed installer.
  • Execution account
    On Windows Vista or higher and Mac OS X, you can specify the type of account the uninstaller should use.You have to add a 'Request privileges' action before this action if you want to run with admin rights.

    Please see the help topic on "Elevation Of Privileges" for more information.