Silent upgrade: Wix installations

This page is for versions 21.10 - 22.9.1 and all HA installations. For versions 23.11 and above, see Silent upgrade (System Manager installations).

Performing a silent upgrade using the System Manager command-line interface (CLI) allows you to create configuration and secrets files, encrypt/decrypt secrets files, and install, uninstall, or upgrade components. This method is useful for large-scale deployments, and it enables easy reinstallation with minor configuration adjustments using the config file, streamlining the process for quick modifications.

Here's why you might consider a silent upgrade:

Efficiency: It speeds up the upgrade process by skipping manual prompts and interactions when deploying software across multiple systems.
Consistency: It uses predefined settings to create a standardized deployment across systems.
For headless systems: If you're working with systems without a graphical user interface (GUI) or in a headless environment, silent upgrades allow for installations without the need for user interaction.
Customization: Tailor upgrades to your specific environment requirements by editing the command-line parameters or configuration files.

Before proceeding, keep these points in mind:

Silent upgrades may need specific configurations. Make sure that you have the necessary details to successfully upgrade the product.
It's important to check logs in Seq if any errors occur. The command prompt window provides basic information, but see the Seq logs for troubleshooting.
You need to have a good understanding of the CLI to choose this upgrade method.

Prerequisites

To use the CLI for an upgrade, the following prerequisites apply:

Ensure that all services, including both server and client components, are shut down.
For external database:
- Mandatory: Back up the external database.
- MSSQL Server 2016 or later installed on a remote server.
For internal database:
- (Optional) Back up the internal database, although it will also be backed up.
Backup and uninstall the clients. This step can be performed either before or after the server upgrade.
Configured Nintex RPA server.
Ensure that you have access to the server hosting the MSSQL database and that you have full credentials, including usernames and passwords, for this database.

Establish an open connection between both servers to ensure optimal functionality.
Ensure that you have installed the latest version of the Nintex System Manager executable (NintexSystemManagerSetup.exe).
The installation bundle zip file (e.g., nintex-rpa-server-24.4.0-full.zip).
(For TLS/SSL installation) The certificate files, such as the Personal Information Exchange file (e.g., kryonaws_full_chain.pfx).

We support different certificate file options: PFX (PKCS#12), CERT, KEY, and PEM files. Make sure you have the necessary files for your environment and ensure that each server in a multi-server installation has a certificate installed.

Run Powershell as an administrator to execute any commands.

Upgrade flow

The steps below show the order an upgrade must follow. See the full reference to commands and arguments, with descriptions and examples, in the CLI Commands table below. The command syntax is nintex-sysmgr-cli <command> <arguments>.

Install Nintex System Manager by executing the CMD command: NintexSystemManagerSetup.exe /S.
- After installation, you can access the folder from anywhere by opening CMD and entering nintex-sysmgr-cli.
- The default installation location for the nintex-sysmgr-cli.exe file is in the System Managerinstallation folder, typically located at C:\Program Files\NintexSystemManager.
(Optional) Store the installation bundle and Nintex System Manager executable file in the same directory. While this step is optional, it can help with easier management. You can do this by specifying the destination directory using the appropriate command arguments.
Run PowerShell as an administrator.
Navigate to the folder that contains the Nintex System Manager executable (NintexSystemManagerSetup.exe).
Run the configTemplate command to generate a config.prod.properties.json file.
Edit the config.prod.properties.json file as required, referring to the list of parameters and their descriptions. Make the necessary changes based on your environment's requirements.
Run the secretsTemplate command to generate a config.prod.properties.secured.json file.
Edit any secrets you want to change and set the relevant secrets for remote third parties, referring to the list of parameters and their descriptions. By default, all passwords are set to a random string that you can change to human-readable passwords. Changing the passwords for third-party applications makes it easier to remember when you log into their user interface.
Run the encrypt command to create an encrypted secrets.zip file.
(Optional) Use the --remove argument to delete the decrypted secrets JSON file after encryption for security. If you don't, you'll receive a prompt to delete the decrypted secrets file, which you can recreate using the decrypt command.
(Optional) Run the validate command to perform data validations.
Run the upgrade command to perform the upgrade using the bundle, edited configuration file, and encrypted secrets files.

CLI commands

When using the install command (--command=install), only the all-in-one server type is available.
In the following commands, whenever you encounter "xx.xx.x," replace it with your preferred version. For example, nintex-sysmgr-cli --command=configTemplate --h=C:\nintex --z=C:\sysmgr\nintex-rpa-server-24.4.0-full.zip --d=C:\sysmgr\config.json.

In the command examples listed below, the nintex-sysmgr-cli, installation bundle zip file, config.json, and secrets.json files are in the C:\sysmgr directory. You can use any directory you want but edit the commands below to match your environment.

The home directory path is what the Nintex System Manager executable uses as the working directory and is where the components are installed.

Command syntax: nintex-sysmgr-cli <command> <arguments>
Command	Arguments	Example and Description
--command=configTemplate	--h - home directory path --z - zip bundle path --d - destination to save the config template file (with file name)	Copy `nintex-sysmgr-cli --command=configTemplate --h=C:\nintex --z=C:\sysmgr\nintex-rpa-server-xx.xx.x-full.zip --d=C:\sysmgr\config.json`
--command=configTemplate		The command generates a config.json file with essential values for installation and server connections. Edit this file according to your environment. Default values are pre-set.
--command=secretsTemplate	--h - home directory path --z - zip bundle path --d - destination to save the secrets config template file (with file name)	Copy `nintex-sysmgr-cli --command=secretsTemplate --h=C:\nintex --z=C:\sysmgr\nintex-rpa-server-xx.xx.x-full.zip --d=C:\sysmgr\secrets.json`
--command=secretsTemplate		The command creates a secrets.json file with connection credentials in plain text. Adjust credentials in secured.config.json for connections to 3rd party servers like your MSSQL server.
--command=encrypt	--h - home directory path --f - unencrypted secrets file --d - destination where to save the encrypted secrets file (with file name) --remove or --rm - delete decrypted secrets file	Copy `nintex-sysmgr-cli --command=encrypt --h=C:\nintex --f=C:\sysmgr\secrets.json --d=C:\sysmgr\secrets.zip --secrets-pass-env=SYSMGR_SECRETS_PASS`
--command=encrypt		This command encrypts your JSON secrets file using the environment variable you set up earlier. For security purposes, we recommend deleting the JSON secrets file after the encrypted file is generated, using the `--remove` argument. Copy `nintex-sysmgr-cli.exe --command=encrypt --secrets-file=C:\sysmgr\secrets.json --dest-file=C:\sysmgr\secrets.zip --remove`
--command=decrypt	--h - home directory path --f - encrypted secrets zip file --d - destination where to save the decrypted secrets file (with file name)	Copy `nintex-sysmgr-cli --command=decrypt --h=C:\nintex --f=C:\sysmgr\secrets.zip --d=C:\sysmgr\secrets.json --secrets-pass-env=SYSMGR_SECRETS_PASS`
--command=decrypt		The decrypt command uses the same environment variable as the encrypt command to decrypt the secrets zip file.
--command=validate	--z - zip bundle path --s - server type --external-config - config file --f - encrypted secrets zip file --output - log the output	Copy `nintex-sysmgr-cli --command=validate --z="C:/sysmgr/nintex-rpa-server-xx.xx.x-full.zip" --s=allInOne --c="C:/sysmgr/config.json" --f="C:/sysmgr/secrets.zip" --output`
--command=install	--h - home directory path --z - zip bundle path --s - server type --c - config file --f - encrypted secrets zip file	Copy `nintex-sysmgr-cli --command=install --h=C:\nintex --z=C:\sysmgr\nintex-rpa-server-xx.xx.x-full.zip --s=allInOne --external-config=C:\sysmgr\config.json --secrets-file=C:\sysmgr\secrets.zip --secrets-pass-env=SYSMGR_SECRETS_PASS`
--command=install		The install command uses the previously generated and edited files (config template and secrets template), and the installation bundle zip file, to install the product and components. All output is logged to Seq. The only currently supported server type is all-in-one.
--command=uninstall	--h - home directory path --z - zip bundle path --s - server type --wipe - should wipe all data (backups, cache, etc.)	Copy Regular Uninstall Package `nintex-sysmgr-cli.exe --command="uninstall" --s="allInOne"`
		Copy Uninstall Wipe package `nintex-sysmgr-cli.exe --command="uninstall" --wipe --s="allInOne"`
		To uninstall using the CLI, you have two options: Regular uninstall: This option removes the product assets, but cache files will remain. If you want to reinstall, the product uses the previously stored data. Uninstall with wipe: This option removes all product data. Data in remote databases and Seq are not removed automatically. For instance, Aerobase data in the database must be manually deleted.

When you use directories containing a space such as C:\sysmgr home folder\subfolder\file name.txt, you must enclose it in inverted commas, for example "C:\sysmgr home folder\subfolder\file name.txt".