Skip to main content
Version: 10.2.8

Upgrade from 10.2.x to 10.2.8.x

The guide describes upgrading to the 10.2.8.x versions of the Work.AI platform. Note that this operation uses the installer, so the procedure is similar to the installation.

Prepare for upgrade​

Before the upgrade, ensure that:

  • You created the additional DNS record for the MinIO UI. See DNS names.

  • You allowed additional ports between servers For ZooKeeper and ETCD. See Ports.

    Pay attention that Work.AI v10.2.8.x requires additional ports 9064, 9079, and 9094 to be opened for the correct Product's operation.

  • 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 SSH access to all Linux hosts.

  • You specified the billing_environment_id and billing_customer_id parameters for the Pendo setup identification.

  • You installed the packages on the Superset server. You also mounted the vds-data directory on the Superset server in case you use an external NFS server. For details, see Prepare for installation | Perform additional setup for Superset server.

note

If you configured LDAP/AD or IDP/SSO and turned off wf_username in Keycloak for the upgrade process, re-enable this user. You can deactivate 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:

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

  5. Repeat steps 3-4 for all fleets.

Check running Business Processes​

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

  1. Go to INSTALL_DIR that contains the installer directory created during the installation of 10.2.0, 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.

If you stopped all of the Business Processes (step 1) but the output from the command is still displaying "There are running business processes..." (step 2), list them and delete them one by one by running the following commands:

# List all Business Processes
$ ./zookeeper/bin/zkCli.sh ls /control-tower/execution/active-instances | egrep '^\[[0-9a-f-]+.*$'
[1b76392d-f629-4800-ba70-3050e20df11f, 548dcb6a-73b1-490d-9436-c22f079494d5]

# Remove BPs one by one
$ ./zookeeper/bin/zkCli.sh delete /control-tower/execution/active-instances/1b76392d-f629-4800-ba70-3050e20df11f
$ ./zookeeper/bin/zkCli.sh delete /control-tower/execution/active-instances/548dcb6a-73b1-490d-9436-c22f079494d5

Destroy all workers​

Before the upgrade, ensure that all the workers are destroyed:

  1. In your browser, open the Marathon UI.

  2. Under Applications, find the worker item.

  3. Find the additional options button and click Destroy.

Stop services​

To stop services:

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.

# IMPORTANT: it is mandatory to stop marathon-apps first. Run the below command only once on any Master server
$ wfmanager stop marathon-apps

# Make sure that all marathon-apps are seen as STOPPED
$ wfmanager status marathon-apps

# Then stop the rest of the product components
$ ./install.sh stop_services full
note

When updating the DR Failover environment, skip Prepare certificate and Download installer sections and execute steps 1-3 from the Deploy DR environment section.

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, for the Standard installation, on the first Master server, add ca.crt, server.crt, and server.key to the PACKAGE_DIR/certificates/ directory. For the Multipoint 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 v.10.2.8.x installer:

  1. Go to INSTALL_DIR that contains the installer directory created during the initial installation, 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 to PACKAGE_DIR:

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

    If Internet access 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.8.x-installer-archive> --strip 1

  5. Copy configuration files for the current environment from BACKUP_DIR to PACKAGE_DIR:

    $ cp -r ../BACKUP_DIR/{license.properties,.agreement} PACKAGE_DIR/

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

  7. After generating the files, in config.yml, check the rpa_deployment_mode property for the updated setup types.

    note

    The default configuration installs RPA without the console session (unified_setup) in the Unified Setup mode.

    If you still need other setup types, change the value of the rpa_deployment_mode property accordingly:

    • vdi: for vdi installation, one Bot per one server.
    • server for standard installation, several Bots per one server.

  8. Fill empty passwords in config.yml.

    $ ./install.sh passwords generate

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

    Work.AI supports Active Directory logins for MSSQL. To switch to MSSQL AD logins, in config.yml, change the corresponding mssql logins to the credentials you created when preparing the database.

    info

    BI workbooks are not published by default during the installation process. To publish them 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

  9. Encrypt config.yml:

    $ ./install.sh encrypt config

  10. Check that your certificates comply with the requirements and generate required internal ones:

    $ ./install.sh certs generate
If you upgrade using the Standard setup approach
  1. On the Master server, generate configuration files as described earlier.
  2. Ensure that PACKAGE_DIR, including the installer package, the /certificates directory, config.yml, rpa.yml, ports.yml, and hosts.yml, are synchronized across all Linux hosts.

Upgrade components​

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

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

  2. Remove the outdated components of the previous installation:

    $ cd PACKAGE_DIR
    $ ./install.sh cleanup rudiments

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

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

  5. Optional.

    For the DR installations: if you are updating a DR Failover environment, execute steps 5-8 from the Deploy DR environment section.

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

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

  7. Clean up 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. Wait several minutes if you see error 503 in a browser right after the upgrade.

Update database connection properties​

After the upgrade is complete, verify if the following Vault properties contain the "trustServerCertificate=true" argument:

  • ct.datasource.url
  • ds.datasource.url
  • ws.datasource.url

Next, complete the following steps:

  1. Make sure the loader.sh script for retrieving and uploading Vault properties is present on the MASTER1 server:

    $ 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 install wf-sec-storage

  2. Get the current values of the ct.datasource.url properties:

    loader.sh wfagent review | grep 'ct.datasource.url'

    • If the trustServerCertificate=true argument is present in the value, you do not need to perform any actions. See the example output with trustServerCertificate=true:

      [INFO ] ct.datasource.url : ct.datasource.url : jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;trustServerCertificate=true;databaseName=workfusion;schema=ct

    • If the trustServerCertificate=true argument is missing, update the value. See the example output without trustServerCertificate=true:

    [INFO ] ct.datasource.url : ct.datasource.url : jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;databaseName=workfusion;schema=ct

    To update the value, perform the following steps:

    1. Copy the current value of the ct.datasource.url property.

    2. Create a new file in the INSTALL_DIR/wf-sec-storage/ directory, for example, INSTALL_DIR/wf-sec-storage/update.properties.

    3. In the file, add a line in the key=value format. Mind that you append the ;trustServerCertificate=true portion to the previous value, for example:

      ct.datasource.url=jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;databaseName=workfusion;schema=ct;trustServerCertificate=true

  3. Verify the values of the ds.datasource.url and ws.datasource.url properties as in step 2:

    loader.sh wfagent review | grep 'ds.datasource.url'
    loader.sh wfagent review | grep 'ws.datasource.url'

    If trustServerCertificate=true is missing, add additional lines to the update.properties file. The example final content of the update.properties file is as follows:

    ct.datasource.url=jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;databaseName=workfusion;schema=ct;trustServerCertificate=true
    ds.datasource.url=jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;databaseName=workfusion;schema=ds;trustServerCertificate=true
    ws.datasource.url=jdbc:sqlserver://MSSQL_HOSTNAME:1433;multiSubnetFailover=true;databaseName=workfusion;schema=ws;trustServerCertificate=true

  4. Add new values to Vault:

    loader.sh wfagent INSTALL_DIR/wf-sec-storage/update.properties

  5. To apply changes, restart Control Tower and Workspace and destroy all currently running workers:

    wfmanager restart workfusion  # restart Control Tower
    wfmanager restart workspace   # restart workspace

Upgrade Analytics server​

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

Back up site configuration​

info

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 server installation directory, for example, c:\workfusion\, as it gets deleted during the upgrade.

To download the custom workbooks from the Analytics server interface:

  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 data sources from the Analytics server interface:

  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. Follow the instructions in the Backup and restore custom Analytics dashboards section to restore custom dashboards.

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​

Custom workers​

Suppose you have changed workers' settings in the platform v10.2.1.x, you can migrate them after the upgrade.

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

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