install4j Help

Configuring Actions


Actions are configured on the Installer->Screens & Actions step. An action performs a configurable unit of work of the installer application.

Actions are attached to screens or they are part of the "Startup sequence" that allows you to perform actions before the installer or uninstaller is displayed. If any one of these actions fails and has a "Quit on failure" failure strategy, the installer application will not be shown.

Most often, actions are added to the "Installation" or "Uninstallation" screens. The advantage of those screens is that they have a progress bar and a status display that is utilized by actions. If a screen does not expose a progress interface, the status and progress messages of attached actions are lost. This is no problem for near-instantaneous actions such as setting an environment variable, but for time-consuming operations the user should be informed about progress, even if it is only an indeterminate progress bar. As an alternative to the "Installation" or "Uninstallation" screens, you can use "Display progress" screens to create additional installation phases.

Some actions have an "affinity" to a particular screen and will suggest to add themselves to that screen, such as the actions in the "Final options" category which would like to go to the "Finish" screen. However, this is only a suggestion to guide you for the most common use cases.

Some actions have an associated screen that allows the user to modify the behavior of the action. For example, the "Install a service" action has a corresponding "Services" screen where the user can decide whether the service should be installed and started when booting. If such a relationship exists, a corresponding notification is displayed after adding an action.

Properties of actions

Common properties of actions are:

  • Action elevation type [Privileges]

    If the action should run in the elevated helper process.An elevated helper process is available on Windows and macOS if the process has been started without admin privileges and the "Request privileges" action has been configured to require full privileges.
  • Condition expression [Control Flow]

    This expression is evaluated to decide whether the action is executed. If the expression or script returns false, the current action will be skipped. This expression or script should not have any side-effects, it will be called while another screen is still being displayed.
  • Rollback barrier [Control Flow]

    If the action should be a rollback barrier. When a rollback barrier is completed, none of the preceding actions will be rolled back. You can use this property to prevent an incomplete rollback of complex changes or to protect actions from rollback when the user hits "Cancel" in the post-install phase.
  • Exit code [Control Flow]

    If the "Rollback barrier" property is selected, and a rollback terminates at this action, this property determines the exit code of the installer. By default, reaching a rollback barrier during a rollback is considered a success, but you can signal a failure by specifying a non-zero exit code here.

    This property is only visible if "Rollback barrier" is selected.

  • Can be executed multiple times [Control Flow]

    If the action can be executed multiple times. If unselected, the action will only be executed once and do nothing for subsequent invocations of the containing screen. The default settings for screens ensure that a screen with actions that cannot be executed multiple times is only shown once. However, if the "Back button" property is changed of if you skip screens programmatically, a screen might be shown multiple times.
  • Failure strategy [Error Handling]

    If an action fails (i.e. returns false), the installer or uninstaller can continue, quit, or ask the user what to do. If you select something other than "Continue on failure", you should enter an error message in the "Error message" property unless the action displays the error itself.

    For "Return to the parent screen", no further actions will be executed and the previous screen will be displayed again. If the action is contained in the "Startup" node, the first screen will be shown and in unattended mode the application will quit.

  • Error message [Error Handling]

    If the action fails, this error message is displayed to the user, otherwise the action fails silently.

Available actions

The following standard actions are available in install4j:

  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.

  Run script

Runs a custom script. The script must return a boolean value. If it returns false, the installation will be canceled.

  Set a variable

Sets a variable by running a custom script. The script can return any java.lang.Object.

  Set messages

Sets the messages in the progress interface.

  Set the progress bar

Change the value of the progress bar or set it to indeterminate mode.

  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.

  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.

  Add a startup executable on Windows and macOS

Add an installed executable to the startup folder on Windows or to the login items on macOS so that it will be started automatically when the user logs in. This action will be automatically reverted by the 'Uninstall files' action.

  Add an executable to the dock

Add an installed executable to the dock on macOS. This action will be automatically reverted by the 'Uninstall files' action.

  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.

  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.

If the application has not yet been started, the arguments to the main method will contain the file name. Subsequent invocations can be intercepted with the com.install4j.api.launcher.StartupNotification class. This action will be automatically reverted by the 'Uninstall files' action.

For macOS, file associations have to be defined on the "Executable info->macOS options" step of the launcher wizard.

  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.

  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.

  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.

  Register a URL handler

Register a URL handler for a custom scheme, so that the launcher is invoked when the user clicks on a link with the specified scheme.

On Windows and Linux, the arguments to the main method will contain the URL. On macOS, the arguments are available from the com.install4j.api.launcher.StartupNotification class. If the "Allow only a single running instance of the application" check box is selected on the "Java invocation" step of the launcher wizard, subsequent invocations are intercepted by the com.install4j.api.launcher.StartupNotification class on all platforms.

This action will be automatically reverted by the 'Uninstall files' action.

For macOS, URL handlers have to be defined on the "Executable info->macOS options" step of the launcher wizard.

  Category: File operations

  Change Windows file rights

Changes 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.

  Copy files and directories

Copy files and directories. This action will be automatically reverted by the 'Uninstall files' action.

  Create a symbolic link

Creates a symbolic link. This action has no effect on Windows.

  Delete files and directories

Deletes files and directory. Directories can be deleted recursively.

  Move files and directories

Moves files and directories. The newly created files are subject to removal by the 'Uninstall files' action.

  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.

  Set the modification time of files

Sets the modification time of files.

  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.

  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.

  Open PDF viewer

Displays a PDF file in a cross-platform PDF viewer. A separate window will be opened.

  Reboot computer

Reboot the computer on Windows and macOS. 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.

  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.

  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.

  Category: HTTP and network

  Add a Windows firewall rule

Add a Windows firewall rule. This action will be automatically reverted by the 'Uninstall files' action.

  Download file

Download a URL and save it to a file

  HTTP request

Make an HTTP request to a specified URL. All common HTTP request methods are supported for REST calls. For mime types starting with text or containing "charset" information, the response body can be saved to an installer variable. To download large files, use the "Download file" action instead.

The action will succeed if a HTTP response code in the 2xx range is received, otherwise it will fail. You can save the response code to a variable to inspect it in a later action.

  Upload file

Upload a file to an HTTP server with a POST request.

  Wait for HTTP server

Wait until an HTTP or HTTPS 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.

  Wait for Socket

Wait until a socket can be connected to. This is useful if you start a non-HTTP server. For HTTP and HTTPS, use the "Wait for HTTP server" action instead.

  Category: JDBC

  Check JDBC connection

Check if a connection can be made to the configured JDBC database. If no connection can be made, the action will fail. If the action is attached to a form screen that queries a database location, set its "Error message" property to an appropriate error message and the "Failure strategy" property to "Return to the parent screen".

  Execute SQL query

Execute a single SQL query and store the result in an installer variable. If only the first row is taken, the row value is stored directly, otherwise the variable will contain an instance of java.util.List with the row values. If the query is for a single column, the row value is the Java object representation of the return type, e.g. java.lang.String for VARCHAR or java.lang.Long for INT.

  Execute SQL script

Execute a single SQL statement or a script of SQL statements.

  JDBC container action

This action allows you to configure connection properties just once and then execute a list of JDBC actions with the same connection.

  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.

  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.

  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.

  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.

  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.

  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.

  Check for running processes

Check for installed launchers and additional running processes on Windows and macOS.

  Modify an environment variable on Windows

Sets, appends to, prepends to or removes an environment variable on Windows. This action can be automatically reverted by the 'Uninstall files' action.

  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.

  Request privileges

Requests configurable administrator privileges. On Windows Vista and higher and on macOS, 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.

  Require installer privileges

Require the same privileges as the ones that were obtained during the installation. On Windows Vista and higher and on macOS, the uninstaller or custom installer application will be restarted with the requested privileges if necessary. This action only has an effect if a "Load response file" action is executed previously.

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

  Run executable or batch file

Runs an executable or a Windows batch file. The action can optionally wait for termination of the executable.

  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.

  Load a response file

Load a response file that has previously been saved with the "Create a response file" action.

  Modify a response file

Update all variables in an existing response file. The action does not delete variables in the response file for which no installer variables are defined, but keeps them as they are.

This action is useful for updating a response file from a custom installer application, where not all installer variables are available.

  Category: Properties files

  Read a properties file

Read a properties file and save a java.util.Map object with the properties to an installer variable. If you use a "Write properties to file" action to write the variable back to disk, the comments on the existing property definitions will be preserved.

  Remove keys from properties file

Remove selected keys from a properties file. The line separator of the properties file is conserved.

  Write properties to file

Write property definitions to a properties file. The properties can come from an installer variable with a java.util.Map object, another properties file or from direct entry.

If the "Merge into existing file" property is selected, the new property definitions will be added to the existing ones.

  Category: Services

  Install a service

Installs a service. On Windows, this is done by executing the service launcher with the appropriate arguments. On Unix, if systemd is detected, a config file will be created in /etc/systemd/system, otherwise a link will be placed in /etc/init.d. On macOS, 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.

  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.

  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.

  Category: Text files

  Fix line feeds

Changes the line feeds of text files to the platform specific type.

  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.

  Modify text files with regular expressions

Modify installed text files by applying a regular expression.

  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.

  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}

  Write text to a file

Write text to a new file or append text to an existing file.

  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

  Schedule update installation

Schedule a downloaded media file to be started upon the next start of a launcher configured accordingly or by calling UpdateChecker.executeScheduledUpdate().

  Shut down calling launcher

Shut down the launcher that called this application if it was started with the com.install4j.api.launcher.ApplicationLauncher API.

  Category: Windows registry

  Change access rights for a key in the Windows registry

Changes 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.

  Delete a key or value in the Windows registry

Delete a key or value in the Windows registry.

  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.

  Set a value in the Windows registry

Set a value in the Windows registry. This action can also create the appropriate key if necessary.

  Category: XML files

  Apply an XSLT transform

Transform an installed file by applying an XSLT stylesheet.

  Count nodes in XML file

Count the occurrences of an XPath expression in an XML file and save the result to an installer variable.

  Insert XML fragment into XML files

Insert an XML fragment into the position defined by an XPath expression. The fragment can replace an existing element node, or it can be inserted as a child or a sibling.

  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.

  Remove nodes from XML files

Remove selected nodes from XML files by specifying an XPath expression.

  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.

  Category: ZIP files and archives

  Create a ZIP file

Create a ZIP file from the specified source files and directories.

  Extract a DMG file on macOS

Extracts the content of a DMG file to an arbitrary location on macOS.

  Extract a TAR file

Extracts the content of a tar or tar.gz file to an arbitrary location.

  Extract a ZIP file

Extracts the content of a ZIP file to an arbitrary location.

  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.

  Modify a ZIP file

Modify the contents of a ZIP file with a configurable list of actions.

  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.

  Execute previous uninstaller

Uninstalls the previous installation of this application in the selected installation directory by executing the previous uninstaller.

  Install files

Install all files in the distribution tree that are contained in the selected installation components.

  Uninstall files

Uninstall all installed files.