Actions are configured on the Installer->Screens & Actions step.
An action performs a configurable unit of work in 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.
Ask whether to retry the action
If the action fails, ask the user whether to retry the action.
This is one button in a message dialog that shows the error message and the available options to react to the failure.
This property is only visible if "Failure strategy" is set to "Ask user".
Ask whether to quit
If the action fails, ask the user whether to quit the installer application.
This is one button in a message dialog that shows the error message and the available options to react to the failure.
This property is only visible if "Failure strategy" is set to "Ask user".
Ask whether to ignore the failure
If the action fails, ask the user whether to ignore the failure and continue.
This is one button in a message dialog that shows the error message and the available options to react to the failure.
This property is only visible if "Failure strategy" is set to "Ask user".
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.
If this action runs with elevated privileges, the uninstaller will be started with elevated privileges by Windows and no unelevated actions can be performed. In the event that you need to execute processes without elevation, set the "Action elevation type" property to "Do not elevate". Note that the Add/Remove item will be registered for the current user only in that case.
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. On Windows, symlinks can by default only be created with elevated privileges.
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 an 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: JSON files
Count occurrences in a JSON file
Count the occurrences of a JSONPath expression in a JSON file and save the result to an installer variable.
Modify JSON files
Modify parts of JSON files specified by a JSONPath expression. Several modification types are available.
Read value from a JSON file
Read one or multiple values from a JSON file as specified by a JSONPath expression and save the result to an installer variable.
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 a URL and save it to 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.
