Upgrade from 10.1.6 to 10.1.6.x

The guide describes the upgrade to the 10.1.6.x version of WorkFusion Intelligent Automation Cloud Enterprise. Note that this operation uses the full installer, so the procedure is similar to the installation.

Prerequisites

Before upgrading IA Cloud Enterprise, make sure that your environment meets the following requirements. Failing to do so results in an extended time of the upgrade and may cause errors.
The environment must meet all the requirements that are listed in the System requirements section:
- Hardware and OS
  
  During the upgrade from the previous version, use the same number of servers you have initially deployed to install 10.1.6. If you want to change the number of servers, perform the clean install. This requirement is valid for all servers, except BEP Agent and RPA, that you can scale to any extent.
- DNS names
  
  Make sure that you have created all domain names listed on the page.
- Ports
  
  Make sure that all ports listed on the page are open.
- RPA server
  
  Make sure that the required Bot Master and Bot Unit users are present on the RPA server.
- Database
  
  Also, make sure that your database has a user with the enabled db_owner role.
- Users and permissions
  
  Also, make sure that installation users on the Analytics and RPA server have either WinRM or RDP access.
- Certificates
  
  Starting from product version 10.1.6.1, the ca.crt requirements have been changed. It must include all intermediate certificates if they exist and a Root CA certificate. Thus for the upgrade from the previous 10.1.x versions you need to copy intermediate certificates from server.crt to ca.crt: both files – server.crt and ca.crt – must include intermediate ones if they exist.
Only for the high-availability setup. Set the external load balancer's parameters and ports, as described in Configure Load Balancer.
You have WorkFusion Intelligent Automation Cloud 10.1.6 up and running.
You have prepared fleets for migration.
No Business Processes are running.
You have backed up the following components:
- Vault properties for all components.
- Zookeeper settings that were changed since the last installation.
- Any system files that were changed since the last installation.
SSH access to Linux hosts is enabled.
If SSO or LDAP authentication is enabled on the existing environment, verify that they are working before upgrading each corresponding component.

Before you start

Back up previous installation

In v.10.1.6.x, you can back up existing INSTALL_DIR and restore WorkFusion IA Cloud Enterprise to the previous version after the upgrade, if needed. Note that the backup files occupy the same amount of disk space as INSTALL_DIR. Before performing the procedure, make sure that there is enough space on the filesystem.

Rollback to the previous state requires the following components to be backed up:

MSSQL database. You can do it according to your standard backup process.
Directory INSTALL_DIR. You can do it during the upgrade.
Shared directories. If you use any existing NAS, back up the following shared directories per your standard process:
- /shared and /vds-data (for the HA mode)
- /vds-data (for the non-HA mode)

Verify prerequisites

After you prepare the environment for the upgrade, you can use the dedicated checking script for verification. For more information, see check readiness.

Save fleet names for Bot Units

To save currently used fleet names for Bot Units, do the following:

Log in to Control Tower, and click Bot Manager.
In the Bot Manager UI window, click on your RPA server to expand the fleets.
Copy the value into the fleet column → Actions → Edit Fleet.
In the window that opens, click Create new, and paste the previously copied value.
Repeat these steps for all fleets.

Stop IA Cloud Enterprise services

For single-point upgrade

For multi-point upgrade

Connect to the server with the previous installation package via SSH and run the following commands as WFUSER:

$ cd PACKAGE_DIR
$ export ANSIBLE_PRIVATE_KEY_FILE="<path_to_ssh_key>"   # Path to SSH key for connection to all Linux servers as WFUSER.
$ export ANSIBLE_REMOTE_USER="WFUSER"                # Application user provided in config.yml.
$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.
$ ./install.sh stop_services full

Connect to all Linux servers via SSH and run the following command as WFUSER on each of them:

$ wfmanager stop all

Prepare application user

Versions 10.1.6.1+ feature only one application user (here, WFUSER) to install and run the Product.

To perform the upgrade, provide the following permissions to the application user:

Grant the sudo permissions.
Provide the SSH access via the SSH-key to all Linux servers from the with the installation package.

If you upgrade the system in the multi-point way, skip this step.
Provide the application user with the owner permissions for PACKAGE_DIR (where the installer was extracted during the initial installation of 10.1.6, for example: /opt/workfusion/wf_installer).
```
$ sudo chown -R WFUSER PACKAGE_DIR
```

Prepare for upgrade

Download and extract installer

note

If you upgrade in the multi-point way:

Connect to each Linux server via SSH and run the following commands as WFUSER on each of them.
Ensure that config.yml, rpa.yml, ports.yml, and hosts.yml are identical on all hosts.

To download and extract the installer, connect to the server with the installation package from the previous version via SSH and run the following commands as WFUSER:

Go to INSTALL_DIR, where the installer directory was created during the initial installation of 10.1.6, for example: /opt/workfusion:
```
$ cd INSTALL_DIR
```
Create the wf_installer_new directory for the new version of the installer. Ensure that the directory is writable for WFUSER.

Note: use only the wf_installer_new name for the directory to store the new installation package; otherwise backup won't start.
```
$ mkdir wf_installer_new
```
Download the installer v.10.1.6.x to INSTALL_DIR/wf_installer_new:
```
$ curl -o '<10.1.6.x-installer-archive>' '<link-to-installer-10.1.6.x>'
```
If Internet access is not available on the server, place the package to the INSTALL_DIR/wf_installer_new directory with any convenient method.

Extract the installer:

$ tar xzf <10.1.6.x-installer-archive> --strip 1

Copy configuration files for the current environment from INSTALL_DIR/wf_installer to INSTALL_DIR/wf_installer_new:

$ cp -r INSTALL_DIR/wf_installer/{license.properties,certificates,.agreement,rpa.yml} INSTALL_DIR/wf_installer_new/

Generate new configuration files from existing ones:

$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.

$ cd INSTALL_DIR/wf_installer_new
$ ./install.sh hosts_yml  generate -e @INSTALL_DIR/wf_installer/hosts.yml
$ ./install.sh config_yml generate -e @INSTALL_DIR/wf_installer/config.yml
$ ./install.sh ports_yml  generate -e @INSTALL_DIR/wf_installer/config.yml

Encrypt config.yml:
```
$ ./install.sh encrypt config
```
Generate required internal certificates:
```
$ ./install.sh certs generate
```

Back up old installation directory

The procedure is optional.

To back up old installation directory (INSTALL_DIR), connect to the server with the new installation package via SSH and run the following commands as WFUSER:

$ cd INSTALL_DIR/wf_installer_new
$ export ANSIBLE_PRIVATE_KEY_FILE="<path_to_ssh_key>"   # Path to the SSH key for connection to all Linux servers as WFUSER
$ export ANSIBLE_REMOTE_USER="WFUSER"                # Application user specified in config.yml
$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"  # Password for decrypting config.yml
$ ./install.sh backup full -e backup_dir=/path/to/backup_dir # Path to the directory to place a backup. Make sure it is writable for WFUSER.

note

The above procedure is intended for the single-point installation. To back up the the directory created during the multi-point installation, in the last command specify <server_role> instead of full. For example,

$ ./install.sh backup <server_role> -e backup_dir=/path/to/backup_dir -c local --limit <current_hostname> # here, <server_role> may be int, app, bepagent, etc.

Check users' passwords

Ensure that users' passwords are valid in config.yml. In most cases, you don't need to change anything in the file. You may proceed further and skip this step. If you encounter issues, for example, an error message with invalid credentials, then:

Open config.yml for editing.

./install.sh edit_config int
# you'll be prompted for the decryption password

Update it with valid passwords.

nexus_admin_pass

mssql_dba_pass
mssql_ct_pass
mssql_ws_pass
mssql_sqc_pass
mssql_rpa_pass
mssql_pm_pass
mssql_dm_pass
mssql_ocr_pass
mssql_automl_mms_pass

Re-run the installation script. The script is idempotent, and it is safe to re-run it.

For example, after the initial 10.1.6 installation, Nexus or MSSQL passwords may be changed manually in the environment. In this case, actualize them in config.yml because the installer will use them during the execution for updating DB schemas and Nexus artifacts).

Upgrade components on servers

Upgrade the components, depending on your installation approach:

Single-point non-HA and HA

Six-servers multi-point

Eight-servers MP

Multi-point HA

Remember to run the following command on the server with the installation package as WFUSER.

Go to INSTALL_DIR/wf_installer_new:
```
$ cd INSTALL_DIR/wf_installer_new
```

Run the following command to set up the application user.

$ export ANSIBLE_REMOTE_USER="WFUSER" # WFUSER provided in config.yml.

Run the following command to remove outdated components of the previous installation:
```
$ ./install.sh cleanup rudiments
```

Prepare the MS SQL server:

$ ./install.sh precheck mssql   # Checks that MSSQL credentials are set correctly in config.yml, Database exists, wf_dba_user exists and has db_owner role
$ ./install.sh configure mssql  # Creates all required schemas in Workfusion DB, creates and maps DB users to provided MSSQL logins, and assigns correct user permissions per schemas

Run the upgrade commands:

$ ./install.sh preinstall full -e skip_bi=true -e skip_rpa=true -e skip_ocrwin=true
$ ./install.sh install full -e skip_bi=true -e skip_rpa=true -e skip_ocrwin=true
$ ./install.sh check full -e skip_bi=true -e skip_rpa=true -e skip_ocrwin=true

Before updating the RPA server, uninstall current RPA and perform a clean installation of new RPA:
```
$ ./install.sh uninstall rpa
$ ./install.sh install rpa
$ ./install.sh check rpa
```

Upgrade the OCR Win server, if you use it instead of Linux OCR:

$ ./install.sh uninstall ocrwin
$ ./install.sh install wf-sec-storage
$ ./install.sh install ocrwin
$ ./install.sh check ocrwin
$ rm -rf ../wf-sec-storage

Cleanup RabbitMQ queues:
1. On the server with the installation packages, run the command:
```
$ ./install.sh stop_services full # stop all services
```
2. On the servers with RabbitMQ (all INT servers for the HA environment; or the APP server for the non-HA one), run the commands:
```
$ wfmanager start rabbitmq
$ rabbitmq-diagnostics ping -q # repeat untill Ping succeeded (echo $? == 0)
```
3. On any server with RabbitMQ (any INT for the HA environment; or APP for non-HA), run the command:
```
$ rabbitmqctl --silent list_queues --vhost bep | awk '{ print $1 }' | xargs -r -L1 rabbitmqctl delete_queue --vhost bep
```
4. On the server with the installation package, run the command:
```
$ ./install.sh start_services full # start all services
```

The upgrade is complete. It may require Control Tower for about 5 minutes to start. So, if you see error 503 in a browser right now, wait a bit.

If your current topology comprises six servers, run the following commands on each Linux server, as WFUSER:

On each Linux server, stop all IA Cloud services:
```
$ wfmanager stop all
```
To verify the status of services, use the command wfmanager status.
On each Linux servers, in the INSTALL_DIR/wf_installer_new, run the following command to remove outdated components of the previous installation:
```
$ ./install.sh cleanup rudiments -c local --limit=<current_server_dns_name>
```

Run the following commands once on any Linux server:

$ ./install.sh precheck mssql   # Checks that MSSQL credentials are set correctly in config.yml, Database exists, wf_dba_user exists and has db_owner role
$ ./install.sh configure mssql  # Creates all required schemas in Workfusion DB, creates and maps DB users to provided MSSQL logins, and assigns correct user permissions per schemas

Install IA Cloud Enterprise components on all Linux servers by following the corresponding guide.
Log in to the RPA server and uninstall RPA components: Control Panel → Programs and Features → RPA (Uninstall).
Install RPA by following the instructions in the section Install RPA package.

Cleanup the RabbitMQ queues to ensure that old workers do not spawn queues:

$ wfmanager stop all        # Run on each Linux server
$ wfmanager start rabbitmq  # Run on all INT servers
$ rabbitmqctl --silent list_queues --vhost bep | awk '{ print $1 }' | xargs -r -L1 rabbitmqctl delete_queue --vhost bep      # Run on first INT server
$ wfmanager start all      # Run on each Linux server

After installing the Linux components, upgrade the OCR Win server (if it exists):
1. Uninstall Win OCR components: Control Panel → Programs and Features → Workfusion OCR (Uninstall).
2. Install Win OCR by following the instructions in section Install OCR Windows server.

If your current topology comprises eight servers, run the following commands on each Linux server, as WFUSER:

On each Linux server, stop all IA Cloud services:
```
$ wfmanager stop all
```
To verify the status of services, use the command wfmanager status.
On each Linux servers, in the INSTALL_DIR/wf_installer_new, run the following command to remove outdated components of the previous installation:
```
$ ./install.sh cleanup rudiments -c local --limit=<current_server_dns_name>
```

Run the following commands once on any Linux server:

$ ./install.sh precheck mssql   # Checks that MSSQL credentials are set correctly in config.yml, Database exists, wf_dba_user exists and has db_owner role
$ ./install.sh configure mssql  # Creates all required schemas in Workfusion DB, creates and maps DB users to provided MSSQL logins, and assigns correct user permissions per schemas

Internal HAProxy

On the APP server, prepare the setup of the component:
```
$ ./install.sh preinstall lb -c local
```

Upgrade the component:

$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decrypting config.yml.
$ cd INSTALL_DIR/wf_installer_new
$ ./install.sh install lb -c local