# Actions: Misc

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Add VM options](#add-vm-options) — `com.install4j.runtime.beans.actions.misc.AddVmOptionsAction`
- [Check for running processes](#check-for-running-processes) — `com.install4j.runtime.beans.actions.misc.CheckRunningProcessesAction`
- [Create a response file](#create-a-response-file) — `com.install4j.runtime.beans.actions.misc.CreateResponseFileAction`
- [Load a response file](#load-a-response-file) — `com.install4j.runtime.beans.actions.misc.LoadResponseFileAction`
- [Modify a response file](#modify-a-response-file) — `com.install4j.runtime.beans.actions.misc.ModifyResponseFileAction`
- [Modify an environment variable on Windows](#modify-an-environment-variable-on-windows) — `com.install4j.runtime.beans.actions.misc.ModifyEnvironmentVariableAction`
- [Modify classpath](#modify-classpath) — `com.install4j.runtime.beans.actions.misc.ModifyClasspathAction`
- [Request privileges](#request-privileges) — `com.install4j.runtime.beans.actions.misc.RequestPrivilegesAction`
- [Require installer privileges](#require-installer-privileges) — `com.install4j.runtime.beans.actions.misc.RequireInstallerPrivilegesAction`
- [Run executable or batch file](#run-executable-or-batch-file) — `com.install4j.runtime.beans.actions.misc.RunExecutableAction`

---

### Add VM options
- **Class:** `com.install4j.runtime.beans.actions.misc.AddVmOptionsAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes
- **Installed files required:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `launcherId` — Launcher | String [context=launcher] | Configuration | — | The launcher that the VM options should be added for. |
| `vmOptions` — VM options | String[] | Configuration | — | 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. In the edit dialog, you have to enter one item per line. VM options that are installer variables with array or collection values (e.g. String[], Object[] or List<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
- **Class:** `com.install4j.runtime.beans.actions.misc.CheckRunningProcessesAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `includeLaunchers` — Include launchers | boolean | Configuration | — | If selected, the operation will check for running launchers in the current installation directory. |
| `additionalExecutables` — Additional executables | File[] | Configuration | — | The additional executables that should be checked. In the edit dialog you can choose files from the distribution tree or enter them manually. Additional executables that are installer variables with array or collection values (e.g. String[], Object[] or List<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. |
| `closeStrategy` — Close strategy | [CloseStrategy](enums.md#closestrategy) | Configuration | — | The strategy used when processes are running. |
| `allowIgnore` — Ignore button | boolean | Configuration | — | Add an "Ignore" button to the dialog. The action will return successfully if the user clicks this button. |
| `timeOut` — Time out for close in ms | int | Configuration | — | The time out for the soft close strategy in milliseconds. |
| `message` — Message | String | Configuration | — | The message to be displayed at the top of the dialog. |

### Create a response file
- **Class:** `com.install4j.runtime.beans.actions.misc.CreateResponseFileAction`
- **Category:** Persistence of installer variables
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — File | File | Configuration | — | The response file that should be created. If it already exists, it will be overwritten. |
| `variableSelectionMode` — Variable selection mode | [VariableSelectionMode](enums.md#variableselectionmode) | Configuration | — | Determines which response file variables are written to the response file. |
| `excludedVariables` — Excluded variables | String[] [context=variableName] | Configuration | `variableSelectionMode`=All except specified response file variables | The variables that should be excluded from the response file. If empty all variables will be used. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |
| `includedVariables` — Included variables | String[] [context=variableName] | Configuration | `variableSelectionMode`=Only specified response file variables | The variables that should be included in the response file. If empty, no variables will be used. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |

### Load a response file
- **Class:** `com.install4j.runtime.beans.actions.misc.LoadResponseFileAction`
- **Category:** Persistence of installer variables
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — File | File | Configuration | — | 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. |
| `excludedVariables` — Excluded variables | String[] [context=variableName] | Configuration | — | The variables in the response file that should be ignored. If empty, all variables will be loaded. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |
| `overwriteStrategy` — Overwrite strategy | [OverwriteStrategy](enums.md#overwritestrategy) | Configuration | — | If "Overwrite existing" is selected, already defined installer variables will be overwritten by variable definitions in the response file. With "Do not overwrite command line", you can give priority to command line variable definitions of the form -Vname=value, but still overwrite previous variable definitions for other variables. |
| `registerForResponseFile` — Register variables for response file | boolean | Configuration | — | If selected, all variables in the response file will be registered as response file variables, except for variables that are excluded or system variables (starting with "sys."). Response file created by subsequent "Create a response file" actions and the automatically created response file by the installer will contain these variables. Note that form screens register bound variables for response files only when they are displayed, so if this option is deselected, the response file created by an update installation may not contain all variables from the original installation. |

### Modify a response file
- **Class:** `com.install4j.runtime.beans.actions.misc.ModifyResponseFileAction`
- **Category:** Persistence of installer variables
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `file` — File | File | Configuration | — | The response file that should be created. If it already exists, it will be overwritten. |
| `variableSelectionMode` — Variable selection mode | [VariableSelectionMode](enums.md#variableselectionmode) | Configuration | `addVariables`=true | Determines which response file variables are written to the response file. |
| `excludedVariables` — Excluded variables | String[] [context=variableName] | Configuration | `variableSelectionMode`=All except specified response file variables | The variables that should be excluded from the response file. If empty all variables will be used. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |
| `includedVariables` — Included variables | String[] [context=variableName] | Configuration | `variableSelectionMode`=Only specified response file variables | The variables that should be included in the response file. If empty, no variables will be used. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |
| `addVariables` — Add response file variables | boolean | Configuration | — | If selected, the specified response file variables are added to the response file. Otherwise, only the existing definitions in the response file are updated with their current values. |

### Modify an environment variable on Windows
- **Class:** `com.install4j.runtime.beans.actions.misc.ModifyEnvironmentVariableAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `type` — Modification type | [ModifyStringType](enums.md#modifystringtype) | Configuration | — | Modification type |
| `variableName` — Variable name | String | Configuration | — | The name of the variable that should be modified. |
| `value` — Value | String | Configuration | — | The value to be set, appended or prepended. |
| `userSpecific` — User specific | boolean | Configuration | — | If the variable is user-specific or system-wide. |
| `revertOnUninstallation` — Revert on uninstallation | boolean | Uninstallation | — | Revert the change automatically on uninstallation if this action is used for an installer. |
| `revertOnlyIfNotModified` — Only if not modified | boolean | Uninstallation | `revertOnUninstallation`=true | Revert the change only if the environment variable hss not been modified in the meantime. This is mainly useful for the 'set' modification type. |

### Modify classpath
- **Class:** `com.install4j.runtime.beans.actions.misc.ModifyClasspathAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes
- **Installed files required:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `launcherId` — Launcher | String [context=launcher] | Configuration | — | The launcher that the classpath should be changed for. |
| `entries` — Classpath entries | String[] [context=entry] | Configuration | — | The classpath entries. In the edit dialog, you have to enter one item per line. Entries that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate entries, this allows you to build a variable length list of entries at runtime. |
| `type` — Modification type | [ModifyStringType](enums.md#modifystringtype) [context=modificationType] | Configuration | — | Modification type |

### Request privileges
- **Class:** `com.install4j.runtime.beans.actions.misc.RequestPrivilegesAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `obtainIfAdminWin` — Try to obtain full privileges if admin user | boolean | Windows | — | If selected 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. |
| `obtainIfNormalWin` — Try to obtain full privileges if normal user | boolean | Windows | — | If selected 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. |
| `failIfNotObtainedWin` — Show failure if requested privileges cannot be obtained | boolean | Windows | — | If selected 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, macOS and Unix. |
| `obtainIfAdminMac` — Try to obtain root privileges if admin user | boolean | macOS | — | If selected 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. |
| `obtainIfNormalMac` — Try to obtain root privileges if normal user | boolean | macOS | — | If selected 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. |
| `failIfNotObtainedMac` — Show failure if requested privileges cannot be obtained | boolean | macOS | — | If selected 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, macOS and Unix. |
| `linuxPrivilegeRequirement` — Linux privilege requirement | [PrivilegeRequirement](enums.md#privilegerequirement) | Linux | — | If set to "Root" the installer must be started as root, otherwise 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, macOS and Unix.If set to "Try to obtain privileges" the installer will start a helper process with pkexec in GUI mode and with sudo or su in console mode. |
| `failIfNotObtainedLinux` — Show failure if requested privileges cannot be obtained | boolean | Linux | `linuxPrivilegeRequirement`=Try to obtain privileges | If selected 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, macOS and Unix. |
| `failIfNotRootUnix` — Show failure if current user is not root | boolean | Unix | — | If selected 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, macOS and Unix. |

### Require installer privileges
- **Class:** `com.install4j.runtime.beans.actions.misc.RequireInstallerPrivilegesAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `failIfNotObtained` — Show failure if required privileges cannot be obtained | boolean | General | — | If set and the privileges that were obtained in the installer could not be obtained by this action, a failure message will be shown and the installer application will be canceled. |

### Run executable or batch file
- **Class:** `com.install4j.runtime.beans.actions.misc.RunExecutableAction`
- **Category:** Miscellaneous
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `executable` — Executable | File | Configuration | — | The file that should be executed. Do not add arguments here, but use the separate "Arguments" property instead. |
| `workingDirectory` — Working directory | File | Configuration | — | The working directory for the execution. |
| `arguments` — Arguments | String[] | Configuration | — | The arguments passed to the executable. Please note that in the edit dialog, each argument starts on a new line. Arguments that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate arguments, this allows you to build a variable length list of arguments at runtime. |
| `useRollbackExecutable` — Use rollback executable | boolean | Configuration | — | If selected, an executable is invoked in the case of rollback. You can configure the executable with the child properties. All other properties, such as redirection and environment variables are shared with the regular executable. |
| `rollbackExecutable` — Rollback executable | File | Configuration | `useRollbackExecutable`=true | The file that should be executed in the case of rollback. Do not add arguments here, but use the separate "Arguments" property instead. |
| `rollbackWorkingDirectory` — Rollback working directory | File | Configuration | `useRollbackExecutable`=true | The working directory for the execution of the rollback executable. |
| `rollbackArguments` — Rollback arguments | String[] | Configuration | `useRollbackExecutable`=true | The arguments passed to the rollback executable. Please note that in the edit dialog, each argument starts on a new line. Arguments that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate arguments, this allows you to build a variable length list of arguments at runtime. |
| `wait` — Wait for termination | boolean | Configuration | — | If the action should wait for termination of the process and check if the return value is 0. |
| `returnCodeVariable` — Variable name for return code | String [context=variableName] (variable→ Integer) | Configuration | `wait`=true | 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. If a timeout has been set and the process is killed after the timeout, the return value will be -10000. |
| `timeout` — Timeout in seconds | int | Configuration | `wait`=true | If set to a value greater than 0, the executable will be killed after that number of seconds if it does not return earlier.In that case, the return value will be -10000. |
| `waitForStreams` — Wait for output streams | boolean | Configuration | `wait`=true | If selected, the action will wait until the output streams of the process are fully written. If the process has launched child processes, this can mean that the action will wait until those child processes have terminated. If that is not desired, please deselect this option. |
| `logArguments` — Log arguments | boolean | Configuration | — | If the arguments should be written into the log file or not. Disabled by default due to security reasons. |
| `stdoutRedirectionMode` — Redirect stdout | [OutputRedirectionMode](enums.md#outputredirectionmode) | Redirection | — | Redirection mode for stdout |
| `stdoutVariableName` — Installer variable name | String [context=variableName] | Redirection | `stdoutRedirectionMode`=To installer variable | An installer variable name to which the stdout output of the executed process is saved. The contents of the variable will not be displayed in the log file. |
| `updateStdoutVariableLines` — Update variable after each line | boolean | Redirection | `stdoutRedirectionMode`=To installer variable | If selected, the variable will be updated after each line, otherwise the variable will be updated once the stream is closed.If you select this property, you can use a "HTML or text display" form component to display a live view of the output by setting its text to the configured installer variable and configuring the caret to follow the end of the document. |
| `stdoutFile` — Redirection file | File | Redirection | `stdoutRedirectionMode`=To file | A file to which the stdout output of the executed process is saved. 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. To use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt. |
| `failOnStdoutFileError` — Fail on error | boolean | Redirection | `stdoutRedirectionMode`=To file | If selected, the action fails if the redirection file cannot be written. Otherwise, errors are silently ignored. |
| `stderrRedirectionMode` — Redirect stderr | [OutputRedirectionMode](enums.md#outputredirectionmode) | Redirection | — | Redirection mode for stderr |
| `stderrVariableName` — Installer variable name | String [context=variableName] | Redirection | `stderrRedirectionMode`=To installer variable | An installer variable name to which the stderr output of the executed process is saved. The contents of the variable will not be displayed in the log file. |
| `updateStderrVariableLines` — Update variable after each line | boolean | Redirection | `stderrRedirectionMode`=To installer variable | If selected, the variable will be updated after each line, otherwise the variable will be updated once the stream is closed.If you select this property, you can use a "HTML or text display" form component to display a live view of the output by setting its text to the configured installer variable and configuring the caret to follow the end of the document. |
| `stderrFile` — Redirection file | File | Redirection | `stderrRedirectionMode`=To file | A file to which the stderr output of the executed process is saved. 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. To use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt. |
| `failOnStderrFileError` — Fail on error | boolean | Redirection | `stderrRedirectionMode`=To file | If selected, the action fails if the redirection file cannot be written. Otherwise, errors are silently ignored. |
| `stdinRedirectionMode` — Redirect stdin | [InputRedirectionMode](enums.md#inputredirectionmode) | Redirection | — | Redirection mode for stdin |
| `stdinString` — Input string | String [context=multiline] | Redirection | `stdinRedirectionMode`=From string | A string that should be fed to the input stream of the executed process. |
| `stdinFile` — Redirection file | File | Redirection | `stdinRedirectionMode`=From file | A file which should be fed to the input stream of the executed process. 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. To use a file in the installation directory, enter a path like ${installer:sys.installationDir}/log.txt. |
| `failOnStdinFileError` — Fail on error | boolean | Redirection | `stdinRedirectionMode`=From file | If selected, the action fails if the redirection file cannot be written. Otherwise, errors are silently ignored. |
| `includeParentEnvironmentVariables` — Include parent environment variables | boolean | 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 macOS. |
| `environmentVariables` — Specific environment variables | Map [context=environmentVariables] | Environment Variables | — | Specify additional or modified environment variables that should be set for the executed process.Use previous values with the syntax ${PATH};additional. |
| `showWindowsConsole` — Show console window | boolean | Windows | — | Show a console window with the console output of the executable. This makes only sense if a command line executable is called. |
| `keepConsoleWindow` — Keep console window | boolean | Windows | `showWindowsConsole`=true | 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. |

