Skip to main content
Version: 10.2.4

Upgrade from 10.1.x to 10.2.4.x

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

note

Only the upgrade option for the six-server topology is currently valid.

Before you start​

The 10.2.4.x non-HA topology requires five servers:

  • MASTER
  • AGENT
  • RPA
  • BI
  • DB

Note the following changes in server roles:

  • The separate INT, APP, and BEP Master servers no longer exist. Instead, WorkFusion has introduced a single MASTER server. It contains all services that previously ran on the three servers. For the single-point installation, MASTER becomes the server to run the setup on.
  • BEP Agent servers are renamed to AGENT servers.

The upgrade starts with preparing the environment to bring the topology to the appropriate state.

Before the upgrade, ensure that:

  • You created the additional DNS record for Keycloak and Minio UI. See DNS names.
  • You allowed additional ports between servers For ZooKeeper and ETCD. See Ports.
  • You added <mssql_pm_user> to SQLAgentUserRole. See Database.
  • You granted view server state permission to <mssql_pm_user>. See Database.
  • 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.
  • You verified that the SSO or LDAP authentication you enabled in the existing environment is working.
  • You stopped APP and BEP Master servers.

Back up previous installation​

You can back up the existing INSTALL_DIR and restore WorkFusion IA Cloud Enterprise to the previous version after the upgrade. Note that the backup files occupy the same disk space as INSTALL_DIR. Before performing the procedure, make sure that there is enough space in the filesystem.

To roll back to the previous state, back up the following components:

  • MSSQL database. You can do it according to your standard backup process.

  • The INSTALL_DIR directory. You can do it during the upgrade.

  • Shared directories. If you use any existing NAS, back up the following shared directories as per your standard process:

    • /shared and /vds-data for the HA mode
    • /vds-data for the non-HA mode

Save fleet names for Bot Units​

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

  1. Log in to Control Tower and click Bot Manager.

  2. In the Bot Manager window, click your RPA server to expand the fleets.

  3. Copy the value into the fleet column → Actions → Edit Fleet.

  4. In the Edit Fleet window, click Create new, and paste the values copied on step 3.

  5. Repeat steps 3-4 for all fleets.

Check running Business Processes​

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

  1. Go to INSTALL_DIR with the installer directory created during the installation of 10.1.x, for example: /opt/workfusion:

    $ cd INSTALL_DIR

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

  1. Stop unnecessary OCR servers.

    IA Cloud v.10.2.4.x doesn't use dedicated OCR servers, so you can stop them. For more details, see the Hardware and OS section. If you plan to retain options for rollback, don't stop the OCR server.

    note

    If no rollback is necessary and you want to use OCR servers as AGENT servers, add their hostnames as agent_hostnames in hosts.yml.

  2. Stop IA Cloud services on the rest of the servers:

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 WFUSER.
$ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml.
$ ./install.sh stop_services full

Prepare application user​

APPLICATION_USER (WFUSER) is required to install and run the Product.

To perform the upgrade, provide the following permissions to APPLICATION_USER:

  1. Grant the sudo permissions.

  2. Provide SSH access via the SSH key to all Linux servers with the installation package.

    If you upgrade the system using the multi-point approach, skip this step.

  3. Provide APPLICATION_USER with the owner permissions for PACKAGE_DIR. This directory contains the installer extracted during the initial installation of 10.1.x, for example: /opt/workfusion/wf_installer.

    $ sudo chown -R WFUSER PACKAGE_DIR

Prepare environment​

note

When updating the DR Failover environment, skip the Prepare environment section and run steps 1-3 from Deploy DR environment.

Prerequisites​

Before upgrading IA Cloud Enterprise, ensure that your environment meets the following requirements. Failing to do so results in an extended time of the upgrade and can cause errors:

Prepare certificates​

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, on the MASTER server, add ca.crt, server.crt, and server.key to the PACKAGE_DIR/certificates/ directory.

You can skip the step if you don't have those certificates. In this case, self-signed certificates get generated automatically during the installation.

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

  1. Go to INSTALL_DIR that contains the installer directory created during the installation of 10.1.x, for example: /opt/workfusion:

    $ cd INSTALL_DIR

  2. 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, the backup doesn't start.

    $ mkdir wf_installer_new

  3. Download the installer v.10.2.4.x to INSTALL_DIR/wf_installer_new:

    $ curl -o '<10.2.4.x-installer-archive>' '<link-to-installer-10.2.4.x>'

    If the Internet is unavailable on the server, download the package to the PACKAGE_DIR directory using any convenient method.

  4. Extract the installer:

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

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

  6. Generate new configuration files from the 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

    After executing ./install.sh hosts_yml generate, in hosts.yml, specify the correct value for keycloak_lb_hostname.

    $ ./install.sh ports_yml  generate -e @INSTALL_DIR/wf_installer/ports.yml
    $ ./install.sh rpa_yml    generate -e @INSTALL_DIR/wf_installer/config.yml
    note

    The new mssql_keycloak_user is introduced with the default password in config.yml. Change it to the password of mssql_keycloak_user that you created on the Prepare the database step.

    Fill empty passwords in config.yml

    $ ./install.sh passwords generate
    note

    Alternatively, you can set the passwords manually. In that case, remember to use only Latin letters and allowed symbols Specify installation parameters.

    info

    In the 10.2.4.x version, IA Cloud supports Active Directory logins. If you want to switch to MS SQL AD logins, in config.yml, change the corresponding mssql logins to the logins and password you created when preparing the database.

    note

    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

  7. Encrypt config.yml:

    $ ./install.sh encrypt config

  8. The server.crt certificate must mandatorily include the end certificate and all intermediate ones if they exist. If your certificates don't comply with the requirements, prepare new ones according to the requirements.

  9. Generate required internal certificates:

    $ ./install.sh certs generate
If you upgrade using the multi-point approach
  1. On the MASTER server, generate configuration files as described earlier.
  2. 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.

Back up old installation directory​

The procedure is optional.

To back up the old installation directory:

  1. Connect to each Linux server via SSH and, on each of them, run the following commands as WFUSER to create a backup directory:

    $ mkdir </path/to/backup_dir>

  2. Connect to the server containing the new installation package via SSH and run the following commands as WFUSER to back up the old installation directory (INSTALL_DIR):

    $ 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 preceding procedure is intended for the single-point installation. To back up the directory created during the multi-point installation, specify <server_role> instead of full in the previous command, 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.

Upgrade components on servers​

caution

Before uninstalling the RPA component, manually copy the log content to preserve the logs. The corresponding folder, and all of its content will be 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:

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

  1. Go to INSTALL_DIR/wf_installer_new:

    $ cd INSTALL_DIR/wf_installer_new

  2. Set up 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.

  3. Remove outdated components of the previous installation:

    $ cd PACKAGE_DIR
    $ ./install.sh cleanup rudiments

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

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

  6. Optional for DR installations:

  7. Before updating the RPA server, uninstall the current RPA and perform a clean installation of a new RPA:

    $ ./install.sh uninstall rpa
    $ ./install.sh preinstall rpa
    $ ./install.sh install rpa
    $ ./install.sh check rpa

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

    3. 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. If you see error 503 in a browser right after the upgrade, wait several minutes.

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.

info

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

  1. Go to a particular site. On the Content tab, click Workbooks. Look for the _custom postfix in their names to identify custom workbooks.
  2. 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:

  1. Go to a particular site. On the Content tab, click Datasources.

  2. In the right corner of the Name column, click More (...), click Download, and save the file as a Tableau datasource.

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

  4. To restore custom dashboards, follow the instructions in the Backup and restore custom Analytics dashboards section.

Upgrade Analytics​

To upgrade the Analytics Server:

  1. On the MASTER server, run the following command:

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

  2. Restart the Analytics server to apply changes.

  3. On the MASTER server, run the following command:

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

Restore custom parameters from previous versions​

note

When upgrading to v.10.2.4.x, you need to manually configure LDAP or AD and IDP or SSO in Keycloak.

Custom workers​

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

caution

When migrating workers from v.10.1.x, you might face an issue that prevents out-of-the-box ML models containing these workers from starting.

This bug is caused by the different configuration approaches in the newer systems. Older workers are configured via YAML files that include the memory:heap parameter. If, in a newer version, the same heap parameter is specified in ZooKeeper to override the YML configuration file, the worker fails to start due to a mismatch between the parameters.

To resolve the issue, modify com.workfusion.spa.core.service.worker.management.utils.ProcessParameterUtils.jvmMemoryLimit(Map<String, Object>) to handle Map with heap inside.

For that, after upgrading, 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.1.0.32/worker.yml, 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.

worker.yml for 10.1.x:

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

command: ${java} -XX:CICompilerCount=2 -XX:+UseSerialGC -XX:MaxMetaspaceSize=${metaspace}M -Xmx${heap}M -XX:+ExitOnOutOfMemoryError -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

worker.yml for 10.2.4.x:

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

command: ${java} -XX:CICompilerCount=2 -XX:+UseSerialGC -XX:MaxMetaspaceSize=${metaspace}M -Xmx${heap}M -XX:+ExitOnOutOfMemoryError -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=${temp.dir}/bcb -jar ${worker.jar} ${config.server.parameters}
cpu: 0.4
memory:
  heap: 1024
  metaspace: 512
health-checks:
  - protocol: MESOS_HTTP
    path: /actuator/health
    grace-period-sec: 180
    interval-sec: 60
    timeout-sec: 10
    max-failures: 3

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.

On the DR Failover environment, disable autostart of its processes. For that, execute step 17 from theDeployment section.