Upgrading WEBCON BPS to a newer version

Applies to version: 2024 R1 and above; author: Konrad Keppert

1. Introduction

Upgrading to a newer version is inevitable for any WEBCON BPS environment due to the acquisition of new functionalities, bug fixes, and security patches. It is therefore in the interest of the system administrator to become familiar with the capabilities of the WEBCON BPS installer and to master the procedure for upgrading the environment.

This article presents a general upgrade procedure in the form of a checklist of tasks to perform before upgrading, a description of each step of the procedure, and some practical tips.

Note: The sample screenshots in this document are from the 2023 environment upgrade to the 2024 version, while the information contained therein is universal. In other cases, appropriate information is included.

2. Before starting the upgrade

2.1 Meeting system requirements

The target version of WEBCON BPS may have different system component requirements. The list of requirements can be found:

• in the installation instructions (PDF file provided in the installer folder),
• in the installer, in the "System verification" step (section 3.3 herein).

If the system requirements are not met, the installer will prevent you from proceeding to the "Component selection" step and thus from performing the upgrade.
 

2.2 License verification

The license package uploaded to the environment contains information about the release number of the version it will work with. The environment can be upgraded to this version or lower. If the installed version is higher than the one in the package, the environment will not work properly. To avoid problems, make sure that the package uploaded to the environment contains a license for the version it is to be installed on.

Information on the highest version of WEBCON BPS that can be installed under the purchased license is available after logging in to the application https://activation.webcon.com.

If necessary, update the license package (section 3.3 of the article WEBCON BPS License activation.
 

2.3 Updating SDK plugins

The SDK plugins are only compatible with the major version of WEBCON BPS for which they were created. If SDK plugins are used in the processes, and the environment will be upgraded to a newer major version (e.g. 2023 à 2024), it is necessary to prepare a new version of them that is compatible with the SDK requirements for the target version of the upgraded WEBCON BPS environment.

SDK plugin providers can find migration documents at https://developer.webcon.com/versions/.
 

2.4 Back up

If the upgrade fails or is interrupted, you need to restore the databases and WEBCON BPS components to the version before the upgrade started in order to be able to work with the environment again. If your servers are hosted in virtual machines, a simple solution may be to take snapshots of these machines.

3. Upgrade

3.1 Installation mode choice

After accepting the license terms, select "Update or expand an existing WEBCON BPS installation" in the installer's main menu.

The installer will then connect to the SQL server hosting the databases of the WEBCON BPS environment. Starting with WEBCON BPS version 2024, if the installer detects that the SQL Server certificate is not trusted, it will display the following message to trust the certificate.

3.2 WEBCON BPS farm

In this step, you will find the information about the upgraded environment that was retrieved from the configuration database. No further steps are required. Click "Next".

3.3 System verification

A list of requirements that must be met in order to upgrade the environment is displayed. The list may include system components and privileges that the user running the installer must have.

Applies to WEBCON BPS 2024 and higher: One of the required components is Java version 11 or higher (in earlier versions of WEBCON BPS, Java was always installed together with the WEBCON BPS Search Server component). If the corresponding Java version is not installed, the installer will give you the option to install it conveniently in the "System verification" step (screenshot below).

The list of components is different for different versions of the platform. For a complete list of system requirements, see the installation instructions included in the installer package.

​​​​​​​​​​​​​​3.4 Component selection

In this step, you need to specify which WEBCON BPS components should be updated (or installed if this has not been done before). By default, it is recommended to select "Update" for all components.

​​​​​​​​​​​​​​3.5 Prerequisites

The prerequisites stage verifies the elements necessary for the upgrade to run properly and for WEBCON BPS to operate correctly after the upgrade. If additional actions are required in the course of the verifications, appropriate messages will be displayed.

Applies to WEBCON BPS 2024 and higher: in case of upgrading from older versions, one of the important changes is updating the version of the Apache Solr engine. This requires reinstalling the entire component (which is the responsibility of the installer), but involves the loss of indexed data. All collections except BPS_Activities (BPS Portal user activities) can be recovered by performing a full database reindexing. For this reason, the installer will suggest making a backup of the BPS_Activities collection so that it can be restored after the upgrade.

After selecting the "Next" button, another window will be displayed to select the backup location.

After the backup has been successfully completed, a confirmation screen will appear.

​​​​​​​​​​​​​​3.6 Component installation

This step displays the list of components that will be changed. If you are installing components that were not previously present, you will be asked to specify the installation path for them. After clicking the "Next" button, the installation of components in a newer version will begin.

When updating the WEBCON BPS Search Server component, the installer may ask for the credentials of the „solr” user (a user with administrator privileges on the Solr server).

Also, when updating the WEBCON BPS WorkFlow Service component, the installer may ask for the credentials of the account running the service. This happens if the option "Remember for the service update" is not checked in the configuration of the WorkFlow Service component.
 

​​​​​​​​​​​​​​3.7 Database upgrade

This stage is responsible for making the changes to the WEBCON BPS databases that are necessary for the new version to work properly. Check the list of databases to be updated and then start the installation process by clicking "Next".

​​​​​​​​​​​​​​3.8 Service status

At this stage, the WEBCON BPS WorkFlow Service is launched. Click the "Start service" button.

The messages of the service will display information about its status. If there is a problem starting the service, check the WEBCON BPS WorkFlow Service event log to determine the cause of the problem.

If the service starts correctly, click "Next".
​​​​​​​

​​​​​​​​​​​​​​3.9 Finish

This step provides a summary of the upgrade – all operations performed. No further actions are required.

The major part of the WEBCON BPS environment upgrade has been completed.

4. Practical tips and information

4.1 Verification of correct operation

In the Windows "Services" section accessible from the Control Panel, verify that the WEBCON BPS Search Service and the WebCon WorkFlow Service can be started correctly.

To verify that the WEBCON BPS Search Service responds correctly, simply search for any phrase in the global search engine of WEBCON BPS Portal (screenshot below).

​​​​​​​​​​​​​​

It is a good idea to open any workflow instance in edit mode (or start a new workflow). In case of problems with the license service, WEBCON BPS Portal works in read-only mode. If it is possible to enter the edit mode on the form, the license service responds correctly.
 

4.2 Loss of the solr user password

The password of the solr administrative user cannot be changed. If the upgrade requires the password of this user (example in the screenshot in step "3.6 Component installation"), but it has been lost, it is necessary to reinstall the WEBCON BPS Search Server component.

The easiest way to solve this problem during the upgrade is to:

- Backup the BPS_Activities collection before the upgrade (this is the only collection whose data cannot be recovered by performing SQL database reindexing).

- Completely uninstall the WEBCON BPS Search Server component.

- Start the upgrade of the environment using the installer of the newer version. In step "3.4 Component selection", indicate WEBCON BPS Search Server for installation and the remaining components for updating.

- Once the upgrade is complete, restore BPS_Activities from the backup and completely reindex all databases using the "SOLR Index Queue" report in Designer Studio.
 

4.3 Upgrading a copy of the production environment

To get an idea of the approximate time it will take to upgrade the production environment, and to ensure that the upgrade goes smoothly, it might be a good idea to perform what is called an environment mirroring, an operation in which the databases of the DEV/TEST environment are overwritten with those of the PROD environment. In this way, it is possible to upgrade the production databases in any other environment.

The environment mirroring procedure is described in the article Mirroring environments (for 2023 Standalone).
​​​​​​​

​​​​​​​4.4 Extended environment

If WEBCON BPS components are installed on more than one application server (HA/failover scenarios), the upgrade must be performed on each machine, as all components must run on the same, newer version of the platform.

The step "3.6 Component installation" will therefore be performed on each server, but databases can only be migrated once. In step "3.7 Database upgrade", the installer checks the number of the last script run, detects that the databases have already been upgraded, and does not run any scripts.

To avoid problems with database migration scripts, do not perform updates on multiple application servers in parallel. Otherwise, if two installers were in the "3.7 Database upgrade" step at the same time, they would run the same scripts on a database, resulting in errors.

It is good practice to update the servers one at a time, although the order is not important in this case.