Migration from BPC 3.* to BPC 4.1

This page describes how to migrate an existing BPC 3 installation to BPC 4.1. To do this, the Elasticsearch data must be converted to the state of a BPC 4.0 installation.

If you have already installed BPC 4.0, follow the instructions at Migration from BPC 4.0 to BPC 4.1

Migration

Stop your BPC 3 installation
Follow the standard installation instructions up to the installation of OpenSearch
In this step, an intermediate migration of the data is performed to transfer it to OpenSearch.
1. Download the Elasticsearch version included with BPC 4.0 (e.g., from https://files.Virtimo.net/BPC/latest/support/4.0.x/release/) and extract it to INSTALLATIONSVERZEICHNIS.
2. Copy your data directory (INSTALLATIONSVERZEICHNIS/elasticsearch/data) to the new Elasticsearch installation (INSTALLATIONSVERZEICHNIS/elasticsearch-7.10.2/data)
3. Start the new Elasticsearch installation and monitor the logs (INSTALLATIONSVERZEICHNIS/elasticsearch-7.10.2/logs). The data will now be automatically adapted to the new Elasticsearch version, which is also required for the migration to OpenSearch. Depending on the volume of data, you should be able to see in the logs after a certain amount of time that all indices are ready.

Your data is now prepared for further migration to BPC 4.1. You can now continue with the migration guide.

The data directory in the BPC 4 installation is migrated automatically. This cannot be transferred back to a BPC 3 installation afterward. Therefore, you should copy or back up the old data directory.

Once the migration is complete, you can remove the two old Elasticsearch installations.

BPC 4.1 remains compatible with Java 11. However, support for Java 11 expired in 2023. A switch to Java 17 is recommended. See the Update Guide - Java

Important Changes

The following lists important changes between BPC 3 and 4. Please read these sections carefully; you may need to make changes on your own.

Please also note the breaking changes at Changelog. All entries between your current version and the target version must be taken into account. This may mean that you need to address Changelog for multiple versions.

The internal module ID for Backend Connections has been renamed

The internal ID of the "Backend Connections" module was historically httpproxy. This has been renamed to backendconnection.

When BPC 4 is started for the first time, the configurations are automatically adjusted.

The permission loadModule_httpproxy must also be changed to loadModule_backendconnection.

For custom developments, code may need to be adjusted. This may affect the following cases, for example:

Setting definitions of type linkedModuleInstance that reference a Backend Connection (_linkedModuleId). Replace httpproxy with backendconnection there.
If backend Connections are created via our API endpoints (or directly in OpenSearch), httpproxy must also be replaced with backendconnection there.
Access to the Backend Connection module: getModuleManager().getModule("httpproxy") → getModuleManager().getModule("backendconnection")
When querying module instances, for example, to filter by a data source or INUBIT connections. There, replace the moduleId check for ` httpproxy ` with ` backendconnection `.

'Deployment Targets' have been renamed

Backend Connections of the type deployment_target were used during deployment to select the source and target. Since this was confusing, they have been renamed to deployment_system.

When BPC 4 is started for the first time, existing configurations are automatically adjusted.

The automatically created deployment system 'dt_local' has been renamed

A deployment system is automatically created for the local BPC. Previously, this had the ID 'dt_local' (dt = deployment target). It is now created with the ID 'ds_local' (ds = deployment system).

When BPC 4 is started for the first time, it is automatically renamed.

Username & password authentication has been removed from the deployment system configuration

Username and password authentication has been removed from the deployment system configuration. Deployment systems can now only be accessed via an API key. If necessary, an API key must first be created on the relevant Deployment System and then stored in the Deployment System configuration.

Deployment API endpoint has been renamed

The API endpoint for querying the configured Deployment Systems has been renamed from /cxf/bpc-deployment/deployment/targets to /cxf/bpc-deployment/deployment/systems.

Data Source Name for Database Connections Has Been Replaced

For database connections (backend connections of type "data_source"), the additional field dataSourceName was used up to BPC 3 to store the data source name and was referenced from various locations. In BPC 4, this was replaced by the instance ID of the backend connection of type "data_source".

When BPC 4 is started for the first time, existing database connections are created with the previous " dataSourceName " as the new instance ID, and the additional field is deleted. Since the previous name of the 'dataSourceName' cannot be carried over exactly (not all characters are allowed in IDs), the references are adjusted accordingly for replication jobs, Log Services, and JAAS DB-based identity providers.

Expiration of API Keys

Previously, the expiration date of issued API keys was specified relatively in the “ expiresIn ” field (e.g., as 360 days or 1 year). This has been replaced by an absolute date in the “ expiresOn ” field (e.g., 2026-06-19T11:30:00.000Z).

When BPC 4 is started for the first time, the relative values are replaced by absolute dates.

Keywords: