Silent upgrade: System Manager installations

This page is for versions 23.11 and above. For versions 21.10 - 22.9.1 and all HA installations, see Silent upgrade (Wix 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.

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

  • Mandatory: Before upgrading from v23.11 to any version up to v24.12, run the script located at C:\Program Files\NintexSystemManager\scripts\recoverConfig.js. This step is required for the upgrade process.

  • Ensure that all services, including both server and client components, are shut down.

  • Ensure the VM is clean and dedicated to the RPA Server installation.

  • Verify that no conflicting versions of .NET are present in the PATH environment variable. *See Known issues below.

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

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

  1. Run PowerShell as an administrator.
  2. Run the existingConfiguration command to generate a config.json and secrets.zip files.

  3. Edit the config.json file as required, referring to the list of parameters and their descriptions. Make the necessary changes based on your environment's requirements.

  4. Run the decrypt command to extract secrets.json from the secrets.zip file.

  5. Modify the necessary values in the secrets.zip file based on your environment's requirements.

  6. Run the encrypt command to create an encrypted secrets.zip file.

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

  8. (Optional) Run the validate command to perform data validations.
  9. Run the upgrade command to perform the upgrade using the bundle, edited configuration file, and encrypted secrets files.

  • 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
  1. --h - home directory path
  2. --z - zip bundle path
  3. --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

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
  1. --h - home directory path
  2. --z - zip bundle path
  3. --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
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
  1. --h - home directory path
  2. --f - unencrypted secrets file
  3. --d - destination where to save the encrypted secrets file (with file name)
  4. --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

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
  1. --h - home directory path
  2. --f - encrypted secrets zip file
  3. --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
The decrypt command uses the same environment variable as the encrypt command to decrypt the secrets zip file.
--command=validate
  1. --z - zip bundle path
  2. --s - server type
  3. --external-config - config file
  4. --f - encrypted secrets zip file
  5. --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
  1. --h - home directory path
  2. --z - zip bundle path
  3. --s - server type
  4. --c - config file
  5. --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
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
  1. --h - home directory path
  2. --z - zip bundle path
  3. --s - server type
  4. --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".

A: You can cancel the installation in PowerShell like you do with any script by pressing CTRL + C.

A: If you're looking to install the product for the first time, please see RPA silent installation for step-by-step instructions on the installation process.

A: You can follow the steps in this topic from the beginning, reconfigure values in the configuration template, and then reinstall.

A: After completing the System Manager installation, proceed with the installation of the Clients (Studio and Robot) and the Dynamic Advanced Commands. Once the client installation is complete, test the products by launching and interacting with Console Plus.