Administration changelog

BPC now supports PKCE (Proof Key for Code Exchange) for OpenID Connect and Keycloak Identity Provider to enable a hardened login flow. To activate this, you need to set the PKCE method in the Identity Provider backend connection and, if necessary, configure this in your Keycloak client.

The driver provided via pax-jdbc-mssql is no longer delivered.

Please ensure that the MSSQL driver used has at least one of the following versions: 10.2.4, 11.2.4, 12.2.1, 12.6.5, 12.8.2, 12.10.2, 13.2.1

If an older driver is being used, it should be replaced. Remove the old driver by deleting it from the deploy directory or by uninstalling pax-jdbc-mssql or the driver itself. Then install a current driver (without the pax-jdbc-mssql feature). See also: Databases

If an error occurs during the migration of an index, the newly created index for the migration will be removed again in order to avoid subsequent errors or to revert to a stable state.

If the configured identity provider is not reachable, it is no longer incorrectly logged that the local Karaf identity provider has been selected as a fallback. Instead, it is indicated that this could be enabled as a fallback.

Ein Fehler wurde behoben, dass der Endpunkt GET /cxf/bpc-core/im/organisations nicht mehr KeyCloak-Gruppen listet, die als Untergruppen definiert sind. Grund war eine Änderung im Verhalten von KeyCloak ab Version > 26.

In the central configuration file (bpc.env.sh), an error in the commented-out option DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_DELETEENTRIESOLDERTHAN was fixed. Previously, activation did not work because the value must be enclosed in quotation marks. The Windows variant was not affected.

With this update, the Karaf version is upgraded to 4.4.8. It is necessary to update the modules bpc-be-core, bpc-be-analysis, bpc-be-forms, and bpc-be-monitor.

For BPC module developers

With the updated Karaf, we are delivering CXF 3.6.8 instead of 3.6.7, which provides Jackson in version 2.19.2.

Please update the CXF version (3.6.8) and Jackson version (2.19.2) in your pom.xml. Check whether you have an Import-Package statement for this version. This must be added or adjusted if you use Jackson features such as the ObjectMapper class.

Http calls via an Http-Proxy or Flow connection filter out the BPC Api-Key header (X-APIKey). Attention: This could affect existing BPC configurations, for example if an INUBIT process is triggered that in turn makes calls to the BPC API using the provided API key. (In this case, it would be better to store a fixed BPC API key in the INUBIT process.)

For boolean values in the settings tables, a combo box is no longer displayed; instead, only the checkbox with the truth value is shown. The value can be changed by clicking, pressing the space bar, or pressing Enter.

Http calls via an Http-Proxy or Flow connection filter out the BPC Api-Key header (X-APIKey). Attention: This could affect existing BPC configurations, for example if an INUBIT process is triggered that in turn makes calls to the BPC API using the provided API key. (In this case, it would be better to store a fixed BPC API key in the INUBIT process.)

For new backend connections of the type HTTP-Proxy and Flow, the option Filter BPC Session is enabled by default.

It could happen that replication got stuck in a certain time window if this window bordered on the present and no records were found.

For the Identity Provider (Backend Connections), a large part was previously configured via a JSON setting. This has been split into individual settings. Existing configurations are migrated automatically. If older deployment exports of Identity Provider components are used, it is best to recreate them.

See also: Create, configure and use Identity Provider, Database as identity provider, Keycloak as an identity provider, Keycloak and dynamic redirect URIs, Deployment constraints

The OpenSearch configuration directory can be configured via OPENSEARCH_PATH_CONF. This allows you to outsource the configuration directory from the OpenSearch directory. As a result, you will no longer overwrite it during an OpenSearch update. See also Outsourcing OpenSearch Configuration.

In the bundle installation file, BPC is now delivered with a configuration directory outsourced to INSTALLATION_DIRECTORY/opensearch_config.

It is recommended to set OPENSEARCH_PATH_CONF in the bpc.env.

A configuration interface for identity providers is now available.

With this update, it is necessary to update the Karaf.

The BPC provides OpenApi-compliant specification files for our APIs. These can be found under Downloads and can alternatively also be accessed dynamically via the BPC, provided this option is enabled. You can find more information in the section BPC-API.

The OpenSearch configuration directory can be configured via OPENSEARCH_PATH_CONF. This allows you to outsource the configuration directory from the OpenSearch directory. As a result, you will no longer overwrite it during an OpenSearch update. See also Outsourcing OpenSearch Configuration.

In the bundle installation file, BPC is now delivered with a configuration directory outsourced to INSTALLATION_DIRECTORY/opensearch_config.

It is recommended to set OPENSEARCH_PATH_CONF in the bpc.env.

For the Identity Provider (Backend Connections), a large part was previously configured via a JSON setting. This has been split into individual settings. Existing configurations are migrated automatically. If older deployment exports of Identity Provider components are used, it is best to recreate them.

See also: Create, configure and use Identity Provider, Database as identity provider, Keycloak as an identity provider, Keycloak and dynamic redirect URIs, Deployment constraints

The plugin can now configure a process that is displayed immediately upon triggering. Additionally, the text and icon can now be freely configured. See also Process Starter Plugin

The option for grouping settings is now initially enabled. It is recommended to use this view, as the settings are displayed together in a common context.

When exporting from the monitor, empty columns are also exported for which there is no OpenSearch mapping yet.

For the process status change, it is now possible to configure the preselection of a value. The preselection is controlled via the configuration preselectState in the setting function_changeStateConfig.

"preselectState": "_first": Always selects the first available value from the dropdown. "preselectState": "<search value>": Selects the first entry that contains the specified text (case-sensitive). Both raw values and display names (from Custom Renderer) can be used.

If exactly one process is loaded and there are exactly two values to choose from, the status field automatically selects the status that does not correspond to the current status.

Example configuration

During replication, Shadow Copy, Tail Sync, and Consistency Check encountered problems if the setting targetIndexCaseSensitivityOfFields was set to lowerCase or upperCase. In the case of Shadow Copy and Tail Sync, this could lead to data loss.

If the BPC is operated in a cluster, it was sometimes not possible to deactivate maintenance mode via the GUI.

The logging configuration has been changed so that session tokens are masked. For new installations of Karaf, this happens automatically. For existing installations, please adjust the configuration file [KARAF]/etc/org.ops4j.pax.logging.cfg. Replace the old line

with the following lines

Since with Keycloak and OIDC the session tokens are UUIDs that are also used elsewhere, we log the first and last four characters here.

If binary files were loaded via INUBIT or another backend system, it could happen that the files were corrupted when downloading or viewing them.

The field Monitor_FileReferenceColumn was missing in the editor.

For existing Karaf installations, add the following value to KARAF/etc/custom.properties:

Dashboard widgets now only display the configuration icon if the user is allowed to edit the dashboard. For this, they need the bpcDashboard_editDashboard permission. Users without this permission can no longer edit dashboard widgets. If editing options (e.g., for custom widgets) should still be offered, the corresponding permission must either be granted or the configuration must be provided through alternative means (e.g., via the widget header).

In the Identity Provider Backend Connections, a health check endpoint can now be configured if the identity provider in use provides such an endpoint. If this is configured, the status can be queried in the status API via /cxf/bpc-core/status/identity-provider. The /cxf/bpc-core/status/health endpoint includes the identity provider status in the health check. For further details, see Configure Identity Provider and Status API. Information on providing the health endpoints in Keycloak can be found in Keycloak as an identity provider.

In the setting moduleHeaderContent, the parameter showSelectionCounter in the metablock can be used to control whether the number of selected records is displayed.

See also Monitor quick functions

Dashboard widgets now only display the configuration icon if the user is allowed to edit the dashboard. For this, they need the bpcDashboard_editDashboard permission. Users without this permission can no longer edit dashboard widgets. If editing options (e.g., for custom widgets) should still be offered, the corresponding permission must either be granted or the configuration must be provided through alternative means (e.g., via the widget header).

In cluster operation, backups only need to be initiated by one node. As a result of the changeover, the metric "bpc_backups_scheduled_jobs" was removed. It contained the number of existing backup jobs.

The start script no longer waits 30 seconds after starting OpenSearch and Karaf. If problems occur where OpenSearch is not available in time, the Watchdog should be used.

The start script no longer makes any changes to the environment. Directories must be configured according to the installation instructions, and JAVA_HOME must also be configured correctly.

The users are now retrieved from Keycloak in blocks. When using external identity providers in Keycloak (e.g., LDAP), longer loading times may still occur if Keycloak performs a synchronization during this process.

The ProzessStarter configuration for windowWidth and windowHeight now correctly affects the window.

The selection of an operator for "number" filters has been restricted to the operator list. The default operator is defined as "=" and, additionally, the default operator can be changed in the filter configuration within the column configuration. See also Configuration of the monitor columns

The right bpcMonitor_editMonitorViews can be set for specific instances to create and modify views in certain monitors by appending the module ID at the end.

See OpenSearch indices view

There is now a description of the internal model_version of the BPC at Versioning of the internal BPC configuration. It also explains that this can have an impact on a Downgrade of the BPC and on Deployment between different BPCs.

The changelog now indicates when there is an update to the internal configuration.

Additionally, an overview of all versions in which a change to the model_version took place is now displayed in Administration changelog. In this context, an overview of versions with Karaf and OpenSearch updates has also been added.

See MinIO as S3 backup for OpenSearch

In Installation, the installation via bundle file is now described. The included start and stop scripts are now described.

Notes added that usually only read permissions are necessary for database connections.

See Backend Connections, Security and Documents.

Instructions for downgrading the BPC taking technical specifics into account. See: * Versioning of the internal BPC configuration * Troubleshooting * Downgrade Guide

Update OpenSearch according to the update guide

Monitors that have an externalReference field with an IGUASU reference can display a link that allows you to jump to the data source in IGUASU. For this, the renderer flow!_!flowRenderer must be set in the monitor column configuration.

See also: BPC → IGUASU

Scripts are provided that allow BPC or Karaf and OpenSearch to be started and stopped.

See Download - Virtimo Fileserver

The user session can be supplemented with customData, which comes from the Additional Info endpoint of the Identity Provider Backend Connection.

See also Add additional organizations/roles/rights and other data to the user session

Replication now also supports, as an alternative to existing database tables/views, the direct entry of an SQL query.

See also sourceCommonTableExpressionQuery in Replication

In the OpenSearch log, there are many logs such as "QueryGroup _id can’t be null, It should be set before accessing it." This is a known bug in OpenSearch that was introduced with version 2.18.0. We have reduced the output as much as we could from our side.

Note: If users already have existing installations of the default instance (BPC Default Reports) in the Analysis Module, it is recommended to set the chart background color to full transparency (RGBA alpha value: 0) under Chart Configuration → Settings → Background Color. This improves visualization when used with the Dark Theme.

Snapshots whose names do not conform to the current naming scheme have blocked the execution of the backups.

If the HTTP proxy used an HTTP/2 connection, the pseudo-header ":status" was forwarded to the client. This leads to an error if interpreted strictly. For example, in this case, nginx reported a 502 Bad Gateway error to the client.

If a deployment was carried out from a BPC with existing monitor views to a BPC that did not yet have any views, an error occurred.

This error has been fixed.

A bug was fixed that prevented instance-specific HTML content editing rights from being granted via the role htmlcontent_editor_<MODULE-ID>.

See OpenSearch indices view

Update OpenSearch according to the update guide

For the hardening of the TLS settings, properties were set in custom.java.security.

If you are not yet using a custom.java.security file via Central configuration file, you should do so.

Existing custom.java.security files should be supplemented with the following entry:

The bpc.env files now also set the security.properties for OpenSearch from the custom.java.security file. As a result, changes in the file affect both Karaf and OpenSearch.

When using a bpc.env, it is recommended to update it. If not already present, the file custom.java.security should be added. The following must be added for this purpose.

See also Central configuration file

With the BPC license, settings can now be protected from modification. This will primarily be used in our cloud installations (K8s). For example, we use the core setting 'backupRepository' to define the configuration of OpenSearch backups in an Amazon S3 bucket, and this should not be changeable via the BPC frontend.

To achieve this, the XML can be extended with the list element NON_WRITEABLE_SETTINGS containing the IDs of the non-editable settings when creating the license.

Excerpt from a sample license:

The settings (example: _core_noinstance_backupRepository) are the same as those used in the OpenSearch index 'bpc-configuration'.

The structure is as follows: <ModuleId>_<InstanceId>_<SettingName>

If it is a setting of a module and not of an instance/component, then the value noinstance is to be used for <InstanceId>. You can find the <SettingName> by displaying the "ID" column in the settings grid in the BPC frontend.

Example: _core_noinstance_backupRepository

We have reduced the number of shards in the Core_IndexTemplates setting to 1. This is also the default setting that Elasticsearch/OpenSearch has been using for new indexes for a few years. This only affects newly created indices. Indices that have already been created are not affected.

The application toolbar has been made slightly lighter. In the admin area, changed text in grids is now displayed with better contrast. The loading animation has been adjusted.

By optimizing access to the OpenSearch Backup API, fewer accesses to the data storage are performed. This reduces the corresponding costs, for example, when using Amazon S3.

Performance increased and heap memory usage reduced. Java has to perform significantly fewer garbage collector calls. This is especially true when the log levels for the BPC packages are set to their default (WARN). This affects the standard BPC modules for Karaf as well as the OpenSearch plugin.

When saving JSON settings, attributes within objects were automatically sorted. This behavior has been disabled. This makes it possible to arrange the order according to your own criteria.

The bpc.env files now also set the security.properties for OpenSearch from the custom.java.security file. As a result, changes in the file affect both Karaf and OpenSearch.

When using a bpc.env, it is recommended to update it. If not already present, the file custom.java.security should be added. The following must be added for this purpose.

See also Central configuration file

The file name of the license can now also be license.xml.virtimo. Previously, it had to be license.xml.bpc. This makes it possible to use a license that is also a valid INUBIT license file at the same time.

The loading of the BPC configuration in the client is accelerated by the change.

For the hardening of the TLS settings, properties were set in custom.java.security.

If you are not yet using a custom.java.security file via Central configuration file, you should do so.

Existing custom.java.security files should be supplemented with the following entry:

The placeholder #user.loginName# is now correctly replaced in the Data_Filter when the dynamic filter # is used.

If the client sends multiple session cookies because several BPCs may be installed on the server, the appropriate session cookie is now taken into account.

In cases with frequent changes to the data, errors could occur in the monitor when displaying detail views. As a result, the entire rendering of the application was disrupted and the page had to be manually reloaded.

Uploaded files are no longer kept entirely in memory. This reduces memory usage and prevents "OutOfMemoryException".

We used CXF version 3.5.4 in our previous Karaf releases. This CXF version provides Jackson in version 2.14.3. Now we ship Karaf with CXF 3.6.5, which provides Jackson in the version 2.17.2.

Please update the CXF version (3.6.5) in your pom.xml. And more important is to update also the used Jackson version (2.17.2). For this check if you have an Import-Package statement for it. This must be added or adjusted when you use Jackson functionality like the ObjectMapper class.

Replace

with

Update OpenSearch according to the update guide

The log level for the BPC plugin in OpenSearch has been reduced from trace to info. This setting can be found in the file opensearch/config/log4j2.properties.

The interface for configuring and creating replication components has been standardized. It is now no longer possible to (de)activate individual replications directly in the list of replication components. This is now done after selecting a replication in the detail view.

The option for "CascadingDynamicFilter" has been added to the administration interface for monitor components.

In the bundle info, which can be accessed via the Karaf console, the time of the last change to the underlying source code is now displayed instead of the build time.

Update OpenSearch according to the update guide

You can use the Log Service API to be redirected directly to the Log Service configuration or to connected monitors. There are two new LogService endpoints that redirect the user to the corresponding BPC pages when called:

See also API documentation: Log Service API

From IGUASU version 3.0.6, it is possible to jump directly from the BPC Flow Processor overview to the IGUASU processor. “Frontend URL” and “System ID” are now available in the Flow Manager. “URL” has been renamed to “Service URL.” Username and password are no longer required. Long descriptions of the processors are displayed in a shortened form, with the full text shown in the tooltip.

If the available disk space falls below defined thresholds, shards are redistributed to other nodes. It can also happen that indices are set to read-only to prevent the disk from filling up.

The value of cluster.routing.allocation.disk.threshold_enabled is now true. This corresponds to the OpenSearch default value.

Fields that contain nested JSON objects receive "formatter": "jsonStringify" in the initial column configuration. This converts the contents into text and displays them in the monitor.

A bug was fixed that caused individual replication jobs not to be correctly distributed across all available nodes when changes were made to the nodes in the BPC cluster.

Although the OpenSearch connection was configured with http, an attempt was made to establish the TLS context based on the configuration. However, if this configuration was incorrect, an error occurred.

The configuration is now ignored, as it is not relevant for http connections.

Nevertheless, it is recommended to use secure connections at this point.

There were various problems when the time zone of the "last update column" in the database table is set to UTC: - The tail sync did not always delete all records. - Instead, it updated all records on each run. - The interaction with replication also became confused.

The documentation for configuring secure network connections has been revised.

See in particular Secure connection (TLS/HTTPS)

Update OpenSearch according to the update guide

A dark theme is available for the BPC. It can be downloaded from the download page.

To switch between installed themes, you can use, for example, the plugin Theme Switcher.

When impersonating other users, the language can no longer be changed in the Keycloak profile of the impersonated user. For this to work, Keycloak must be correctly configured so that impersonator information is passed along via an active scope.

Karaf access via SSH is described in more detail and useful notes have been added.

The following documentation pages have been changed.

The following pages have been revised:

Update OpenSearch according to the update guide

A breaking change was accidentally introduced. The User Account Plugin no longer displays the language selection, even though the "changeLanguage" option is enabled. The option must now be called "languageSelector".

If you update to BPC 4.2.6 or newer, the option will be renamed automatically.

See also User Account Menu

When configuring the Identity Provider of type Keycloak, the configuration of a dedicated admin user is no longer required. All actions in the integrated user management are now performed in the context of the current user. This means that these users must be equipped with all necessary roles in Keycloak. With this adjustment, actions can also be correctly assigned to individual users in the Keycloak audit log. See also Keycloak as an identity provider.

Due to this change, the maximum valid session duration in BPC is no longer influenced by the corresponding setting in Keycloak. It must now be set in the file de.virtimo.bpc.core.cfg under the setting de.virtimo.bpc.core.auth.oidc.sessionExpirationMinutes. The default value is equivalent to 8 hours. If the session duration in Keycloak is shorter, the session checker in BPC will also terminate the session. However, there may be a delay if there is still an AccessToken for the user that has not expired.

Additionally, BPC itself no longer blocks the impersonation of users with the "bpcadmin" role. This must now be configured in Keycloak and is described under Impersonate users with Keycloak.

It is now possible to create new users via the integrated user management in Keycloak or to change the name, email, and password of existing users.

While loading the BPC, the version number of the Core Common Package (Fe-Core) is determined and stored in the local storage. If this version number differs from the one stored during the previous load, the local storage is cleared.

A breaking change was accidentally introduced. The User Account Plugin no longer displays the language selection, even though the "changeLanguage" option is enabled. The option must now be called "languageSelector".

If you update to BPC 4.2.6 or newer, the option will be renamed automatically.

See also User Account Menu

When configuring the Identity Provider of type Keycloak, the configuration of a dedicated admin user is no longer required. All actions in the integrated user management are now performed in the context of the current user. This means that these users must be equipped with all necessary roles in Keycloak. With this adjustment, actions can also be correctly assigned to individual users in the Keycloak audit log. See also Keycloak as an identity provider.

Due to this change, the maximum valid session duration in BPC is no longer influenced by the corresponding setting in Keycloak. It must now be set in the file de.virtimo.bpc.core.cfg under the setting de.virtimo.bpc.core.auth.oidc.sessionExpirationMinutes. The default value is equivalent to 8 hours. If the session duration in Keycloak is shorter, the session checker in BPC will also terminate the session. However, there may be a delay if there is still an AccessToken for the user that has not expired.

Additionally, BPC itself no longer blocks the impersonation of users with the "bpcadmin" role. This must now be configured in Keycloak and is described under Impersonate users with Keycloak.

It is now possible to create new users via the integrated user management in Keycloak or to change the name, email, and password of existing users.

It is now possible to specify references to external resources when writing audit information. For example, it is possible to refer to the IGUASU instance that created the entry.

The configuration grid_showHeader is obsolete as it causes errors. The behavior of the header has been controlled for quite a while using the parameter moduleHeader_enabled.

In the Flow module, a distinction can be made between IGUASU and INUBIT as instance types.

See System monitoring (metrics for Prometheus)

For the HTML Content module, instance-specific roles can now be assigned for editing: htmlcontent_editor_<MODUL_ID> See also: HTML Content module (user-defined content)

JSESSIONID cookie has been deactivated

Update OpenSearch according to the update guide

If an IP pinning error occurs, you can now log in normally in the browser after reloading the page. The error will not be displayed again (unless the IP changes again).

When activating maintenance mode on a single node (in cluster operation), replication was sometimes not stopped. This issue has been resolved. When updating, it is especially important that OpenSearch is also updated.

In current Karaf versions, Karaf-specific environment variables for setting JVM memory have been removed and must be replaced with an alternative.

Linux

Please replace in bpc.env.sh

with

and adopt the values accordingly.

Windows

Please replace in bpc.env.cmd

with

and adopt the values accordingly.

See also Central configuration file and Karaf

In current Karaf versions, Karaf-specific environment variables for setting JVM memory have been removed and must be replaced with an alternative.

Linux

Please replace in bpc.env.sh

with

and adopt the values accordingly.

Windows

Please replace in bpc.env.cmd

with

and adopt the values accordingly.

See also Central configuration file and Karaf

Backend core version must match the OpenSearch plugin. Either update this manually or install the new OpenSearch version.

The JAR license files (file name bpc-be-license.jar) can no longer be used and must be replaced by XML-based license files (file name license.xml.bpc). If you are still using an old JAR license file, please contact support to obtain a new license file.

Only relevant for module developers When using the BPC JsonEditor (xtype bpcJsonField or bpcCodeEditorWindow.json), the optional JSON schema is now passed via schema and no longer via jsonSchema.

The additional component of Karaf called 'Decanter' is used to write the Karaf logs to the OpenSearch index 'bpc-logs'. With a new installation of Karaf, this component is already pre-installed and nothing needs to be done. If an existing Karaf installation cannot or should not be replaced, it can also be installed using the Karaf console (Internet connection required).

The forceJson option is no longer available on the HTTP Proxy APIs.

Update OpenSearch according to the update guide

Only relevant for module developers When using the BPC JsonEditor (xtype bpcJsonField or bpcCodeEditorWindow.json), the optional JSON schema is now passed via schema and no longer via jsonSchema.

The additional component of Karaf called 'Decanter' is used to write the Karaf logs to the OpenSearch index 'bpc-logs'. With a new installation of Karaf, this component is already pre-installed and nothing needs to be done. If an existing Karaf installation cannot or should not be replaced, it can also be installed using the Karaf console (Internet connection required).

New status endpoint for querying the role of individual nodes in cluster operation. This endpoint can now be used to check whether a node has the "master" role or not. See also BPC API /cxf/bpc-core/status/clustermaster

For existing installations, the file bpc-be-dashboard.jar can be removed without replacement and deleted from the KARAF/deploy directory. The dashboard module now consists only of the file bpc-fe-dashboard.war.

Update OpenSearch according to the update guide

The JAR license files (file name bpc-be-license.jar) can no longer be used and must be replaced by XML-based license files (file name license.xml.bpc). If you are still using an old JAR license file, please contact support to obtain a new license file.

The forceJson option is no longer available on the HTTP Proxy APIs.