Upgrade from 10.1.2 to 10.1.6.x

The guide describes the upgrade from 10.1.2.x to 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.

note

During the upgrade from the previous IA Cloud Enterprise version, you can only use the current 8-server topology and cannot switch to the new 6-server one, supported in v. 10.1.6.x. If you want to run the Product on the new topology, perform the clean install.

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 meets all the requirements from the System requirements section:
- Hardware and OS
- DNS names
- Ports
  
  Make sure that all ports that are listed on the page are open. Note that the ports have been changed since 10.1.2, so verify carefully that all required ports 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. The external load balancer's settings and ports are configured, as described in Configure Load Balancer. Note that v. 10.1.6.x features the new load balancer's port 8202. Ensure that this port is configured on your load balancer.
You have WorkFusion Intelligent Automation Cloud 10.1.2 up and running.
No Business Processes are running.
You have prepared fleets for migration.
You have backed up the following components:
- Directories /opt/workfusion/workfusion and /opt/workfusion/workspace.
- Vault properties for all components.
- Zookeeper settings if changed since the last installation.
- Any system files if changed since the last installation.
The SSH access to Linux hosts is enabled.
If SSO or LDAP authentication is enabled on the existing environment, verify that it works before the corresponding component's upgrade.

important

If you want to use MSSQL Active Directory (Kerberos) logins in 10.1.6.x, ensure that:

The MS SQL server is added to the domain.
Server Principal Name (SPN) for the MS SQL server exists within the Active Directory schema.
SPN for the MS SQL server corresponds to the value provided in hosts.yml for the mssql_hostname parameter.
SPN for the MS SQL server is registered for the account used to run the MS SQL service process.
Active Directory logins are created for MSSQL.
All servers within the environment have network access to the Domain Controllers' ports.

Before you start

Verify prerequisites

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

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 opened window, click Create new, and paste the previously copied value.
Repeat these steps for all fleets.

Stop all services

Stop all services according to your installation way:

For single-point setup

For multi-point setup

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

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

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

$ wfmanager stop all

Prepare database tables for models import

To prepare the database for upload of new AutoML models, in your database, run the following commands as mssql_automl_mms_user or mssql_dba_user:

DELETE FROM workfusion.automl_mms.model_version
DELETE FROM workfusion.automl_mms.model
DELETE FROM workfusion.automl_mms.artifact_version
DELETE FROM workfusion.automl_mms.artifact
DELETE FROM workfusion.automl_mms.resource_version
DELETE FROM workfusion.automl_mms.resource

Prepare application user

Previous versions of IA Cloud Enterprise required two Linux users: installation and application ones. Version 10.1.6.x features 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 a 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.2, for example: /opt/workfusion/wf_installer).
```
$ sudo chown -R WFUSER PACKAGE_DIR
```

Download and extract installer

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.2, for example: /opt/workfusion:
```
$ cd INSTALL_DIR
```
Create a backup directory (here, BACKUP_DIR) for the previous version of the installer. Ensure that the backup directory is writable for WFUSER:
```
$ mkdir BACKUP_DIR
```
Move the contents of your PACKAGE_DIR to the backup directory. As a result, directory PACKAGE_DIR must be empty before proceeding with the upgrade:
```
$ cd PACKAGE_DIR
$ mv * ../BACKUP_DIR
$ mv .agreement ../BACKUP_DIR
```
Download the installer v.10.1.6.x to PACKAGE_DIR:
```
$ curl -o '<10.1.6.x-installer-archive>' '<link-to-installer-10.1.6.x>'
```
If Internet access is not available on the server, download the package to the PACKAGE_DIR 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 BACKUP_DIR to PACKAGE_DIR:
```
$ cp -r BACKUP_DIR/{license.properties,certificates,.agreement} PACKAGE_DIR/
```

Generate new configuration files from 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 rpa_yml    generate -e @../BACKUP_DIR/config.yml
$ ./install.sh ports_yml  generate -e @../BACKUP_DIR/config.yml

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

note

If you upgrade the Product in a multi-point way:

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

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
```
Note: you need to verify your passwords to ensure that marathon_web_pass in config.yml does not contain the ":" symbol, as it is not supported and causes the marathon services to fail. Other reasons may be error messages during installation related to invalid credentials.
Re-run the installation script. The script is idempotent; it is safe to re-run it.

For example, after the initial 10.1.2 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 for updating DB schemas and Nexus artifacts.

Upgrade components on servers

Upgrade the components according to your installation approach:

Single-point HA and non-HA

Multi-point non-HA

Multi-point HA

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

Go to the PACKAGE_DIR:
```
$ cd PACKAGE_DIR
```

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_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:

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

Run the following commands 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 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>
```

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

To upgrade 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 decryption of config.yml.
$ cd PACKAGE_DIR

$ ./install.sh install lb -c local

INT Server

To upgrade the component on the Integration Server:

Run the following commands as the root user:
```
$ ./install.sh preinstall int -c local
```

Run the following commands as WFUSER:

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

$ ./install.sh install int -c local
$ ./install.sh check int -c local

BEP Master Server

To upgrade the component on the BEP Master server:

Run the following commands as the root user:

$ ./install.sh preinstall bep-master -c local

Run the following commands as WFUSER:

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

$ ./install.sh install bep-master -c local
$ ./install.sh check bep-master -c local

BEP Agent Server

To upgrade the component on the BEP Agent server:

Run the following commands as the root user:

$ ./install.sh preinstall bep-agent -c local

Run the following commands as WFUSER:

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

$ ./install.sh install bep-agent -c local
$ ./install.sh check bep-agent -c local

To upgrade multiple BEP Agent servers, on each BEP Agent server:

Run the following commands as the root user:

$ ./install.sh preinstall bep-agent --limit bep-agent1.example.com

Run the following commands as WFUSER:

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

$ ./install.sh install bep-agent -c local --limit bep-agent1.example.com
$ ./install.sh check bep-agent  -c local --limit bep-agent1.example.com

APP Server

To upgrade the component, on the APP server:

Run the following commands as the root user:
```
$ ./install.sh preinstall app -c local
```

Run the following commands as WFUSER:

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

$ ./install.sh install app -c local
$ ./install.sh check app -c local

OCR Server (Linux)

To upgrade the component on the OCR Linux server:

Run the following commands as the root user:
```
$ ./install.sh preinstall ocr -c local
```

Run the following commands as WFUSER:

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

$ ./install.sh install ocr -c local
$ ./install.sh check ocr -c local

RPA server

To upgrade the component on the RPA server:

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.

Clean RabbitMQ queues

Clean up 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

Upgrade OCR Win (optional)

After installing the Linux components, upgrade the OCR Win server (if it exists):

Uninstall Win OCR components: Control Panel → Programs and Features → Workfusion OCR (Uninstall).
Install Win OCR by following the instructions in section Install OCR Windows server.

note

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 WFUSER:

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 outdated components of the previous installation:
```
$ cd /opt/workfusion/wf_installer
$ ./install.sh cleanup rudiments -c local
```

On the INT server, run the following commands to prepare MS SQL:

$ ./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 the IA Cloud Enterprise components on all Linux servers by following the corresponding guide.
After installing the Linux components, 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.

Clean up 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

Upgrade Analytics server

Migrate database

To migrate databases for the Analytics server, on the INT server, go to the <package_dir> directory, and execute the following command:

./install.sh migrate bi

You can also migrate the databases after the installation. In this case, run the above command and restart the Analytics server to apply the changes.

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

note

Download custom workbooks and datasources to separate directories. For example, c:\patch_10_1_6_backup\workbooks\ and c:\patch_10_1_6_backup\datasources\.

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

To download the custom workbooks from the Analytics server UI:

Go to a particular site, and, 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, and, 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 a plus symbol ("+") in the titles, except for the first and last two underscores.

Upgrade Analytics

To upgrade the Analytics Server:

For single-point upgrade

For multi-point upgrade

On the server with downloaded installation package, run the following command:
```
$ cd PACKAGE_DIR
$ ./install.sh uninstall bi
```
Restart the Analytics server to apply changes.
On the server with downloaded installation package, run the following command:
```
$ ./install.sh preinstall bi
$ ./install.sh install bi
$ ./install.sh check bi
```
To restore custom dashboards, follow the instructions in the section Backup and restore custom Analytics dashboards.

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

Copy the following script and execute it in PowerShell.

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

$env:win_user="username" # The value of "bi_user" which 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" which 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 section Install Analytics Server.
To restore custom dashboards, follow the instructions in the section Backup and restore custom Analytics dashboards.

Restore custom workers from previous versions

If you have changed workers' settings in IA Cloud 10.1.2, you can migrate your changes after the upgrade.

For that, after upgrading to IA Cloud 10.1.4.1, on the BEP Master server, open the file with workers' settings (for example, /opt/workfusion/vds-data/workers/app/com.workfusion.spa.ct/worker-app/10.1.0.6/worker.yml for Control Tower), and enter the previous corresponding settings, such as memory, CPU, and so on. Note that the structure of the new file differs from the previous one.

File worker.yml for 10.1.2:

#cat /opt/workfusion/vds-data/workers/app/com.workfusion.spa.ct/worker-app/10.1.0.2.1/worker.yml

command: ${java} -XX:MaxMetaspaceSize=128M -Xmx${memory}M -Dgroovy.use.classvalue=true -Dgroovy.target.indy=true -Dfile.encoding=UTF8 -Dexecution.task.queue.input=${tasks.queue} -Dlogging.path=${log.dir} -Dlogging.file=${log.file} -Djava.io.tmpdir=${temp.dir} -Dwebharvest.machine.config.bundle.dir=${working.dir}/bcb -jar ${worker.jar} ${config.server.parameters}

cpu: 0.25
memory: 1024

File worker.yml for 10.1.6.x:

# cat /opt/workfusion/vds-data/workers/app/com.workfusion.spa.ct/worker-app/10.1.0.6/worker.yml

command: ${java} -XX:CICompilerCount=2 -XX:+UseSerialGC -XX:MaxMetaspaceSize=${metaspace}M -Xmx${heap}M -Dgroovy.use.classvalue=true -Dgroovy.target.indy=true -Dfile.encoding=UTF8 -Dexecution.task.queue.input=${tasks.queue} -Dlogging.path=${log.dir} -Dlogging.file=${log.file} -Djava.io.tmpdir=${temp.dir} -Dwebharvest.machine.config.bundle.dir=${working.dir}/bcb -jar ${worker.jar} ${config.server.parameters}

cpu: 0.25
memory:
  heap: 1024
  metaspace: 128

Check the upgrade

Once the update is completed, check the WorkFusion Platform with Business Process (BP) and Manual Task. The OCR must be activated. For more information, see post-installation steps.

WorkFusion Documentation

10.1.6.2

Hardware

Install Linux components

Security settings in Control Tower

note

Prerequisites

important

Before you start

Verify prerequisites

Save fleet names for Bot Units

Stop all services

Prepare database tables for models import

Prepare application user

Download and extract installer

note

Check users' passwords

Upgrade components on servers

Internal HAProxy

INT Server

BEP Master Server

BEP Agent Server

APP Server

OCR Server (Linux)

RPA server

Clean RabbitMQ queues

Upgrade OCR Win (optional)

note

Upgrade Analytics server

Migrate database

Backup site configuration

note

Upgrade Analytics

Restore custom workers from previous versions

Check the upgrade