Upgrade from 10.2.x to 10.2.2

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

Prepare for upgrade

Before the upgrade, ensure that:

No Business Process or Manual Task is running.
You prepared fleets for migration.
You backed up the following components:
- The /opt/workfusion/workfusion and /opt/workfusion/workspace directories
- Vault properties for all components
- ZooKeeper settings changed since the previous installation
- Any system files changed since the previous installation
You enabled the SSH access to all Linux hosts.

note

If you configured LDAP/AD or IDP/SSO and disabled wf_username in Keycloak for the upgrade process, re-enable this user. You can disable it again after the upgrade.

Ensure that config.yml containes correct wf_username and wf_password.

Save fleet names for Bot Units

To save the 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 your RPA server to expand the fleets.
Copy the value into the fleet column → Actions → Edit Fleet.
In the Edit Fleet window, click Create new, and paste the values copied earlier.
Repeat steps 3-4 for all fleets.

Check running Business Processes

Before the upgrade, check that no Business Processes are running:

Go to INSTALL_DIR that contains the installer directory created during the installation of 10.2.0, for example: /opt/workfusion:
```
$ cd INSTALL_DIR
```

Check the output of the following command:

./zookeeper/bin/zkCli.sh ls /control-tower/execution/active-instances | egrep -qo '^\[[0-9a-f-]+' && echo 'There are running business processes. Please stop them first to continue upgrade.' || echo 'There are no running business processes. You are OK to continue update procedure.'

Continue the update procedure if the command displays the following message: "There are no running business processes. You are OK to continue update procedure." Otherwise, stop the running processes first.

Stop services

To stop 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 APPLICATION_USER:

$ 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_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.
$ wfmanager stop marathon-apps
$ ./install.sh stop_services full

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

$ wfmanager stop marathon-apps
$ wfmanager stop all

Prepare certificates

In 10.2.2, the server.crt certificate must mandatorily include the end certificate and all intermediate ones if they exist. Ensure that your certificates comply with the requirements.

Then, for the single-point installation, on the first MASTER server, add ca.crt, server.crt, and server.key to the PACKAGE_DIR/certificates/ directory. For the multi-point installation, do that on all Linux servers.

$ ls -la PACKAGE_DIR/certificates/
total 24
drwxr-xr-x.  3 ec2-user ec2-user   78 Sep 24 14:47 .
drwxr-xr-x. 12 ec2-user ec2-user 4096 Sep 27 17:20 ..
-rw-r--r--.  1 ec2-user ec2-user 2984 Sep 24 14:42 ca.crt
-rw-r--r--.  1 ec2-user ec2-user 4835 Sep 24 14:42 server.crt
-rw-r--r--.  1 ec2-user ec2-user 1674 Sep 24 14:42 server.key

Verify prerequisites

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

Download installer

To download and configure the installer v.10.2.2:

Download the installer to PACKAGE_DIR:
```
$ curl -o '<10.2.2-installer-archive>' '<link-to-installer-10.2.2>'
```
If the Internet access is unavailable on the server, download the package to the PACKAGE_DIR directory using any convenient method.

Extract the installer:

$ tar xzf <10.2.2-installer-archive> --strip 1

Copy configuration files for the current environment from BACKUP_DIR to PACKAGE_DIR:
```
$ cp -r ../BACKUP_DIR/{license.properties,.agreement} PACKAGE_DIR/
```
Generate new configuration files from the existing ones:
```
$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.

$ cd PACKAGE_DIR
$ ./install.sh hosts_yml  generate -e @../BACKUP_DIR/hosts.yml
$ ./install.sh config_yml generate -e @../BACKUP_DIR/config.yml
$ ./install.sh ports_yml  generate -e @../BACKUP_DIR/ports.yml
$ test -f ../BACKUP_DIR/rpa.yml && cp -f ../BACKUP_DIR/rpa.yml rpa.yml || ./install.sh rpa_yml generate
```
important

In the 10.2.2 version, IA Cloud supports Active Directory logins for MSSQL. If you want to switch to MSSQL AD logins, in config.yml, change the corresponding mssql logins to the logins and password you created when preparing the database.
note
Starting from 10.2.2, BI workbooks are not published by default during the installation process. If you need them to be published during the installation, go to config.yml and set the publish_bi_dashboards variable to True. Another option to publish BI workbooks is to run the following command at any time after the installation is completed.
```
$ ./install.sh install bi_workbooks -e publish_bi_dashboards=true
```
Encrypt config.yml:
```
$ ./install.sh encrypt config
```
Check that your certificates comply with the requirements and generate required internal ones:
```
$ ./install.sh certs generate
```

If you upgrade using the multi-point approach

On the MASTER server, generate configuration files as described earlier.
Ensure that PACKAGE_DIR, including the installer package, the certificates folder, config.yml, rpa.yml, ports.yml, and hosts.yml, are synchronized across all Linux hosts.

Check users' passwords

Ensure that config.yml contains valid user passwords. 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 master
# 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
mssql_keycloak_pass

Re-run the installation script.

For example, after the initial 10.2.1.x installation, you may change the Nexus or MSSQL passwords manually in the environment. In this case, actualize them in config.yml because the installer uses them to update DB schemas and Nexus artifacts.

Upgrade components on servers

caution

Before uninstalling the RPA component, manually copy the log content if you want to preserve the logs as the corresponding folder and all of its content gets deleted.

Log locations:

bot-agent logs: ..\RPA\bot-agent\logs
worker logs: ..\RPA\logs
nginx logs: ..\RPA\nginx\logs
WFSvc logs: ..\RPA\tools\logs

Upgrade the components, depending on your installation approach:

Single-point non-HA and HA

Multi-point install

Multi-point HA

Remember to run the following command on the MASTER server as APPLICATION_USER.

Run the following command to set up the application user:

$ export ANSIBLE_PRIVATE_KEY_FILE="<path_to_ssh_key>"   # Path to SSH key for connection to all Linux servers as WFUSER.
$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.

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

Run the following commands:

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

Clean up old workers via Marathon API. For that, on the first MASTER server (default marathon_port: 8480) run the following command. Remember to replace default values in it with your relevant data.
```
$ curl -kv -X DELETE -u 'marathon:<marathon_web_pass>' https://127.0.0.1:<marathon_port>/v2/groups/worker?force=true
```
Note: during the upgrade, you must complete the workers' killing step before Business Processes are started. Otherwise, old workers are not destroyed and prevent new ones from running. This can lead to a system breakdown, and Business Processes cannot be processed.

Verify the installation:

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

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

Clean up RabbitMQ queues:

On the server with the installation packages, run the command:
```
$ ./install.sh stop_services full # stop all services
```

On the server with RabbitMQ (the first MASTER server in the HA mode or the MASTER server), run the commands:

$ wfmanager start rabbitmq
$ rabbitmq-diagnostics ping -q # repeat untill Ping succeeded (echo $? == 0)
$ rabbitmqctl --silent list_queues --vhost bep | awk '{ print $1 }' | xargs -r -L1 rabbitmqctl delete_queue --vhost bep

On the server with the installation package, run the command:
```
$ ./install.sh start_services full # start all services
```

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

On each Linux server, run the following commands as APPLICATION_USER:

Stop all IA Cloud services:
```
$ wfmanager stop all
```
To verify the status of services, use the wfmanager status command.
In the PACKAGE_DIR, run the following command to remove outdated components of the previous installation:
```
$ ./install.sh cleanup rudiments -c local --limit=<current_server_dns_name>
```

On any Linux server, run the following commands once:

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

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

Clean up the RabbitMQ queues to ensure that old workers don't spawn queues:

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

Before starting installation, ensure that config.yml, ports.yml, rpa.yml, hosts.yml, and the /certificates directory are the same on all hosts.

To upgrade components, run the following command on the server with the installation package as APPLICATION_USER:

On all Linux servers, prepare the environment variables:

$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"  # Run on each Linux server to disable password prompt (not mandatory, just for convenience)

On all Linux servers, enter the PACKAGE_DIR directory and run the following command to remove the outdated components of the previous installation:
```
$ cd /opt/workfusion/wf_installer
$ ./install.sh cleanup rudiments -c local
```

Run the following commands once on any MASTER 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

On all Linux servers, install the IA Cloud Enterprise components by following the corresponding guide.
Clean up old workers via Marathon API. For that, on the first MASTER server (default marathon_port: 8480) run the following command. Remember to replace default values in it with your relevant data.
```
$ curl -kv -X DELETE -u 'marathon:<marathon_web_pass>' https://127.0.0.1:<marathon_port>/v2/groups/worker?force=true
```
Note: during the upgrade, you must complete the workers' killing step before Business Processes are started. Otherwise, old workers are not destroyed and prevent new ones from running. This can lead to a system breakdown, and Business Processes cannot be processed.
Log in to the RPA server and uninstall RPA components: Control Panel → Programs and Features → RPA (Uninstall). After that, remove the RPA folder.
Re-install RPA by following the instructions in the Install RPA package section.

Clean up the RabbitMQ queues to ensure that old workers don't spawn queues:

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

Upgrade Analytics server

Back up site configuration

Before upgrading the Analytics components, connect to the BI server via RDP as a Windows Administrator user and save all your custom workbooks and datasources to a predefined location on a local disk.

important

Download custom workbooks and datasources to separate directories, for example, c:\10_2_0_backup\workbooks\ and c:\patch_10_2_0_backup\datasources\.

Don't save backup files in the Analytics (BI) server installation directory, for example, c:\workfusion\ as it gets deleted during the upgrade.

To download the custom workbooks from the Analytics server UI:

Go to a particular site. On the Content tab, click Workbooks. To identify custom workbooks, look for the _custom postfix in their names.
In the right corner of the Name column, click More (...), click Download, and save the file as a Tableau workbook.

To download the custom datasources from the Analytics server UI:

Go to a particular site. On the Content tab, click Datasources.
In the right corner of the Name column, click More (...), click Download, and save the file as a Tableau datasource.
Remember to rename the custom dashboards by replacing all occurrences of the underscore character ("_") with the plus symbol ("+") in the titles, except for the first and last two underscores.
To restore custom dashboards, follow the instructions in the Backup and restore custom Analytics dashboards section.

Upgrade Analytics

For single-point upgrade

For multi-point upgrade

To upgrade the Analytics Server:

On the MASTER server, run the following command:

$ cd /opt/workfusion/wf_installer
$ ./install.sh uninstall bi

Restart the Analytics server to apply changes.

On the MASTER server, run the following command:

$ ./install.sh preinstall bi
$ ./install.sh install bi
$ ./install.sh check bi

To upgrade the Analytics Server:

On the Analytics (BI) server, launch the New PowerShell ISE.

Launch PowerShell ISE as Administrator and copy the following script and execute it in PowerShell on the relevant Analytics server:

# UNINSTALL TABLEAU SERVER
# FILL IN THE PARAMETERS BELOW
$install_dir   = "c:\workfusion" # The value of "install_dir" you've set in config.yml during Linux servers installation.

$env:win_user="username" # The value of "bi_user" you've set in config.yml during Linux servers installation.
$env:win_pass='"password"' # Leave single and double quotes in place. Replace only word password. The value of "bi_pass" you've set in config.yml during Linux servers installation.
# =========================================
$package_dir   = "${install_dir}\WorkFusionAnalyticsServer"

Write-Host "Uninstalling filebeat"
$service = Get-WmiObject -Class Win32_Service -Filter "name='filebeat'"
    if ($service) {
    $service.StopService()
    Start-Sleep -s 1
    $service.delete()
    }

Write-Host "Uninstalling metricbeat"
$service = Get-WmiObject -Class Win32_Service -Filter "name='metricbeat'"
    if ($service) {
    $service.StopService()
    Start-Sleep -s 1
    $service.delete()
    }

Write-Host "Stop PostgreSQL process"
$proceses = "postgress"
        Get-Process | Where-Object {$proceses.Contains($_.Name)} | Stop-Process -Force

Write-Host "Uninstall WorkFusion Analytics Server"
$path = Get-ChildItem -Path $install_dir\WorkFusionAnalyticsServer\packages -Recurse tableau-server-obliterate.cmd
        if ($path) {
        &$path.FullName -y -y -y
        }

Write-Host "Uninstall PostgreSQL Server"
$app = Get-WmiObject -Class Win32_Product | Where-Object {$_.Name -match "psql"}
        if ($app) {$app.Uninstall()}

Write-Host "Remove installation directory"
If (Test-Path $install_dir){
Get-ChildItem -Path $install_dir -Recurse | Remove-Item -force -recurse
Remove-Item $install_dir -Force
}

Restart the Analytics server to apply changes.
Install Analytics (BI) server by following the instructions in the Install Analytics Server section.

Restore custom parameters from previous versions

Custom workers

If you have changed workers' settings in IA Cloud 10.2.1.x, you can migrate them after the upgrade.

For that, after upgrading to IA Cloud 10.2.2, on the MASTER server, open the file with workers' settings for Control Tower, for example, /opt/workfusion/vds-data/workers/app/com.workfusion.spa.ct/worker-app/10.2.1.5/worker.yml, and enter the previous corresponding settings, such as memory, CPU, and so on.

Upgrade Business Processes

Migrate your Business Processes with Manual Tasks that use qualifications. To do that, refer to the following guides:

Check upgrade

Once the upgrade is complete, check the WorkFusion Platform with Business Process (BP) and Manual Task. The OCR must be activated. For more information on post-installation checks, see Install components.

WorkFusion Documentation

10.2.2

Hardware

Install Linux components

Keycloak administrator guide

Prepare for upgrade

note

Save fleet names for Bot Units

Check running Business Processes

Stop services

Prepare certificates

Verify prerequisites

Download installer

important

note

If you upgrade using the multi-point approach

Check users' passwords

Upgrade components on servers

caution

Upgrade Analytics server

Back up site configuration

important

Upgrade Analytics

Restore custom parameters from previous versions

Custom workers

Upgrade Business Processes

Check upgrade