Merging two WEBCON BPS environments

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

Introduction

Until recently, making applications available under two independent URLs (e.g., Helpdesk and HR portal) required maintaining two separate environments. However, this inconvenience was eliminated with the introduction of the Application Hub functionality in version 2025 R2. As a result, keeping two environments for this purpose has become unnecessary and merging them is now preferable.

This article describes the steps that should be taken to merge two WEBCON BPS environments, thereby transferring business applications along with their created documents, histories, and attachments.

NOTE: The environment merge operation should only be carried out in justified cases and must be preceded by thorough testing in non-production environments. The risks are listed at the end of the article.

Procedure

The procedure assumes that one of the environments (hereafter referred to as the source environment) will be migrated into another, already operating environment (hereafter referred to as the target environment).

1. Updating both WEBCON BPS environments to the same version

All WEBCON BPS databases must have exactly the same version (down to the build number) in order to function correctly within a single environment after the merge. Therefore, both environments must be updated to the same version.

It is considered a good practice to update the environment to the latest available version. The installer can be downloaded from the WEBCON Community website.

2. Ensuring license availability

As a result of merging environments, the migrated applications will operate based on the license package activated in the target environment.

It is necessary to verify whether the number of licenses available in the target environment is sufficient to handle all processes, users, and functionalities. Otherwise, you will need to contact your customer service consultant and ensure that the required licenses are available in the target environment.

For each type of license, the following may occur:

• an increase in the number of licensed users of Portal, Designer Studio, or Designer Desk,
• an increase in the number of accesses based on the Single-Solution Access License,
• migrated applications may use functionalities not covered by the licenses in the target environment (e.g., OCR Framework, SDK Framework, Advanced Analytics Framework, AI Tokens).

Detailed information on available licenses can be found in the article WEBCON BPS Licenses – WEBCON Community.

3. Creating an empty content database in the target environment

For a content database to work with the WEBCON BPS environment, two conditions must be met:

• the ContentDatabases table (in the configuration database) must contain the appropriate entry with the name of the content database,
• the database must be linked to the Workflow Service so that it can be handled by it.

To simplify configuration, it is possible to create a new content database in the target environment using the Tools for application management (WEBCON BPS installer). The name of this database should match the name under which the source database will be recreated. In this case, the installer will automatically ensure that the above conditions are met. As a result, once the source environment database is recreated, the system will immediately recognize the new content database.

If more than one content database is being migrated, the above operation must be performed for each of them.

There is no need to prepare the structure for attachment and archive databases in advance – references to them will be included in the recreated content database.

4. Creating new BPS groups and users

The list of external users (BPS Users) and BPS groups is stored in the configuration database. Since this database will not be recreated, it is necessary to create this data in advance in the target environment.

Detailed information about BPS users and groups can be found in the HELP documentation entry Users and Groups | WEBCON BPS.

NOTE: If the merged WEBCON BPS environments use different synchronization sources, it may be necessary to migrate permissions within the transferred content database.

5. Recreating source databases from backup

The content, attachment, and archive databases of the source environment must be recreated on the same SQL Server instance where the target environment databases are located.

If the source database names are already in use on the target instance (e.g., both environments use a content database named “BPS_Content”), the databases must be recreated under new names.

The name of the recreated content database should match the name of the new database created in step 3 (it should be overwritten).

The configuration database must not be recreated.

6. Granting permissions to restored databases

For the WEBCON BPS platform to function properly, the account specified during installation as the Database owner (a dedicated SQL login or the domain account of the application pool) must have db_owner permissions for all environment databases.

After recreating the source databases on the target SQL Server instance, these permissions must be granted to the appropriate account.

7. Changing BPS database names

Recreating source databases under new names results in the loss of relationships between them. Relationships between databases are stored within tables.

Example: In the content database, the table WFAttachmentDatabases, column ADB_Name stores the names of attachment databases linked to the current content database.

A list of occurrences of all references to specific database names can be found in the article Changing WEBCON BPS database name – WEBCON Community. These values must be modified in the restored databases.

8. Adjusting the network infrastructure

The source WEBCON BPS environment configuration may have enabled communication with external systems, e.g., an SMTP server for sending notifications, Exchange mailboxes, or network shares. From the target application server, such communication may not be possible. In this case, changes must be made to allow communication with these systems (or replace them with other available ones).

9. Updating the Portal address in process configuration

Applications migrated from the source environment will operate under a new address. Therefore, if this address is used in process configuration (e.g., in business rules, forms, or Hyperlink action/form field), it must be overwritten.

10. Updating MSSQL connections and database names in configuration

Recreating and renaming source databases in the new SQL Server instance (see points 5 and 7) affect any dedicated MSSQL connections (MSSQL Database | WEBCON BPS) to the content database, causing them to stop working. Therefore, they must be updated by changing the address, name, and/or credentials of the account used for the connections.

If SQL queries (data sources, Run an SQL procedure actions, business rules containing the SQL COMMAND function) include explicitly defined database names, these must also be updated if they have changed.

            11. Adjusting integrations with the public BPS Portal API

Recreating databases in the new environment will cause integrations with the public API of the source environment’s Portal to stop working. Not only will the Portal URL change, but the API application credentials will also be lost. These are stored in the configuration database and are not transferred during migration.

Therefore, it is ESSENTIAL to:

• register new API applications in the target environment,
• update the Portal address and API application credentials in the external systems that integrate with the migrated WEBCON BPS applications.

More information about integrations can be found in the HELP documentation Integrations | WEBCON BPS.

12. Full reindexing of databases in Solr

The final step is to add the Index process or entire database task to the Solr indexing queue so that data from the migrated workflow instances is added to the Solr search database. This ensures that they can be searched in the BPS Portal and are available in reports based on the SearchIndex source.

This step should be performed at the very end, after confirming that the migrated applications function correctly in the target environment, including process permissions and permissions for individual workflow instances. Permission data at the workflow instance level is also sent to the Solr database.

More information about the Solr indexing queue: Solr Indexing Queue | WEBCON BPS.

Risks

• The need to schedule a maintenance window for adapting the recreated applications in the target environment. During this time, work on the source environment should be suspended to avoid inconsistencies or data loss.
• A potential extension of the maintenance window time if external providers are involved in the process (e.g., integrators using the public BPS Portal API).
• Additional load on the target environment:
  • larger volume of data in SQL Server and Solr databases,
  • increased number of requests to be processed by the application server,
  • increased number of operations to be processed and queues to be handled by the Workflow Service.

Therefore, disk space in the target infrastructure should be prepared in advance. In addition, after the merge process is completed, services should be monitored so that server resources can be scaled up if necessary, or the environment expanded with additional WEBCON BPS components (Expanding the WEBCON BPS installation).

• Insufficient licenses in the package used in the target environment.
• Different collation settings between the source and target databases. Such a situation may prevent the system from working correctly and requires adjusting the collation of the source databases to match the target environment.

A good practice to minimize risk is to perform the entire procedure in a non-production environment first. To better replicate production conditions, it may be worth aligning the TEST/DEV environments with production databases beforehand. The procedure for aligning environments is described in the article Mirroring environments (for 2023 Standalone) – WEBCON BPS Community.

It is also important to adapt the Maintenance Plan running on the target SQL Server instance so that it includes index and statistics maintenance for the recreated databases. The procedure for creating such a plan is described in the article SQL Maintenance – Dedicated maintenance mechanism for large BPS databases: indexes and statistics – WEBCON BPS Community.

Summary

This article discussed the general procedure for merging two environments, i.e., transferring business applications (together with their created data) from one environment to another, assuming that both are production environments.

The article also highlighted potential risks that should be considered before starting the migration. The best practice to minimize these risks is to first go through the procedure using non-production environments.

In the case of more non-standard scenarios not covered in this article, it may be necessary to contact the WEBCON Technical Support Department, available at WEBCON Support.