Follow the guideline using Helm charts for yuuvis® Momentum version updates:
>> Version Updates

When updating your yuuvis® Momentum installation from version 2021 Winter LTS to version 2022 Winter LTS, manual configuration changes are required for some services.

Breaking Changes

The following Breaking Changes are incompatible changes we had to deploy into operation, and therefore you—as a yuuvis® user—need to be aware of them and take action accordingly.

Infrastructure

Support of Keycloak Version 19

To use Keycloak version 19, it is required to manually adjust the endSessionUri parameter for each tenant in the application-oauth2.yml configuration file.
Action: In each tenant configuration, remove the redirect URI from the URL as shown below for the testyuuvis example tenant.

up to Keycloak version 15:

endSessionUri: http://${keycloak.host}/auth/realms/testyuuvis/protocol/openid-connect/logout?redirect_uri=${redir}

for Keyclaoak version 19:

endSessionUri: http://${keycloak.host}/auth/realms/testyuuvis/protocol/openid-connect/logout

Core

Performance Optimization for CONFIGSERVICE

This feature is a subsequent change applied to version 2022 Spring as well as 2021 Winter (LTS). Please find details in the release information and in the breaking change description for version 2021 Winter.
>> Product Version 2021 Winter LTS | Breaking Changes

Validation of Internal JSON Web Tokens

The internal endpoint of the AUTHENTICATION service for the validation of internal JSON Web Tokens (JWTs) is now available via a different URL.
>> GET /jwt/verify

Action: Custom microservices that called the endpoint /authentication/jwt/verify have to use the URL http://authentication-internal/jwt/verify instead.

Tenant-specific Database Configuration

It is now possible to configure different databases to be used for storing metadata of individual tenants. Configurations for previous product versions are not supported anymore. The spring.datasource parameters in the application-dbs.yml configuration file are ignored.

Action: If you use the TENANT-MANAGEMENT service in your installation, apply the breaking change for the METRICS service configuration first. Afterwards, apply the new configuration to the core services as described here. To continue using the same database for all tenants, replace the spring.datasource parameters as shown in the example below in your application-dbs.yml configuration in the Git root directory.

The spring.datasource parameters used up to product version 2022 Autumn:

spring.datasource.url: jdbc:postgresql://abc/def
spring.datasource.username: yuuvis
spring.datasource.password: changeme123
spring.datasource.driver-class-name: org.postgresql.Driver

The new configuration structure used as of product version 2022 Winter:

storage:
    databases:
        defaultdb:
            datasource: defaultds
            predicate: 'spel:false'
            default: true
    datasources:
        defaultds:
          url: 'jdbc:postgresql://abc/def'
          username: yuuvis
          password: changeme123
          driver-class-name: 'org.postgresql.Driver'

To use different databases for individual tenants, please read the documentation of the application-dbs.yml configuration file.

Client Services & Client Development

USERSERVICE

Migration of User Information Endpoints.

The user information endpoints GET /userservice/api/users and GET /userservice/api/users/{userId} are not available anymore.

Action: Use the endpoints GET /api-web/api/users/users and GET /api-web/api/users/{userId} instead.

Service-specific Configuration

The USERSERVICE does not call the identity provider itself anymore. Thus, the USERSERVICE does not require the application-userservice.yml configuration file as it contains only Keycloak-specific parameters. The file can be removed.

New Microsoft JDBC Diver for SQL Server

If you use Microsoft SQL Server as database for the USERSERVICE, the corresponding JDBC driver requires an SSL connection.

Action: To continue working without SSL, append encrypt=false to the connection string in your configuration.

Option 1: Set environment variable

You can change the USERSERVICE configuration via environment variable in the deployment, e.g.:

- name: SPRING_DATASOURCE_URL
  value: jdbc:sqlserver://sqlserver2019-mssql-latest.sqlserver2019:1433;databaseName=erebus;encrypt=false

Option 2: Use YML configuration file and profile

Create an application-userservicedb.yml configuration file with following parameter:

spring.datasource.url: 'jdbc:sqlserver://${db.host:localhost}:${db.port:1433};databaseName=${db.name:yuuvis};encrypt=false'

Start the USERSERVICE with the additional userservicedb profile:

- name: SPRING_PROFILES_ACTIVE
  value: userservicedb,mssql,swagger

Developer Libraries

Angular Version Update

The client libraries use Angular 14 now. In case you extended your client with further (third party) libraries, please ensure that they are compatible with Angular 14.
Action: If necessary, update your external libraries to a version that supports Angular 14.

Task Properties in Inbox

The inbox provided by the @yuuvis/core library uses the briefRepresentation parameter of the Web-API gateway bpm-controller endpoints as described below. Thus, the retrieved tasks are presented with a reduced data set to the users of a client application.
Action: If you want to display the full property set of tasks, set disableBriefRepresentation for the inbox service.

Web-API Gateway

New Swagger UI Version

The new Swagger version is available under a new URL.

Action: Adjust the endpoint URL pattern in authentication-prod.yml configuration file has follows:

...
### api-web
  - endpoints: /api-web/swagger-ui.html,/api-web/swagger-ui/**,/api-web/**/v3/api-docs/**
  ...
...

bpm-controller Endpoints

The optional query parameter briefRepresentation is available for the task retrieval endpoints. Per default, the response will contain only a reduced data set in order to reduce the processing time.
Action: In order to keep the behavior of the previous versions, set the query parameter briefRepresentation=false for each request to the corresponding endpoint.

Business Process Managagement

BPM Engine

New Microsoft JDBC Diver for SQL Server

If you use Microsoft SQL Server as database for the BPM-ENGINE service, the corresponding JDBC driver requires an SSL connection.

Action: To continue working without SSL, append encrypt=false to the connection string in your configuration.

Option 1: Set environment variable

You can change the BPM-ENGINE service configuration via environment variable in the deployment, e.g.:

- name: SPRING_DATASOURCE_URL
  value: jdbc:sqlserver://sqlserver2019-mssql-latest.sqlserver2019:1433;databaseName=erebus;encrypt=false

Option 2: Use YML configuration file and profile

Create an application-bpmdb.yml configuration file with following parameter:

spring.datasource.url: 'jdbc:sqlserver://${db.host:localhost}:${db.port:1433};databaseName=${db.name:yuuvis};encrypt=false'

Start the BPM-ENGINE service with the additional bpmdb profile:
```
- name: SPRING_PROFILES_ACTIVE
  value: bpmdb,swagger
```

Tenant Management

Tenant Management API

New Swagger UI Version

The new Swagger version is available under a new URL.

Action: Adjust the endpoint URL pattern in authentication-prod.yml configuration file has follows:

...
### tenant-management
  - endpoints: /tenant-management/swagger-ui.html,/tenant-management/swagger-ui/**,/tenant-management/**/v3/api-docs/**
  ...
...

idm-controller Endpoints

The optional query parameter briefRepresentation is available for the endpoint GET /tenant-management/api/idm/users. Per default, the response will contain only a reduced data set in order to reduce the processing time. Especially, roles and groups of the listed users are not included in the default response anymore.
Action: In order to keep the behavior of the previous versions, set the query parameter briefRepresentation=false for each request to the endpoint.

METRICS Service

As the METRICS service still uses only one database for the data of all tenants, it uses an own configuration file with its own database connection parameters now.

Actions:

Create a copy of the previoulsy used application-dbs.yml configuration file and save it as application-dbstmp.yml configuration file. The file should now contain the spring.datasource parameters as shown in the following example.
```
spring.datasource.url: jdbc:postgresql://abc/def
spring.datasource.username: yuuvis
spring.datasource.password: changeme123
spring.datasource.driver-class-name: org.postgresql.Driver
```
In the METRICS service deployment, replace the dbs profile by the dbstmp profile.
Continue with the database reconfiguration of the core services.

Configurations Enabling new Features

Some new features require manual configuration in order to operate properly after the update to the new yuuvis® Momentum version.

Core

Fail-safe AUTHENTICATION Service

In order to enable the shared usage of the session state for multiple instances of the AUTHENTICATION service, the session state has to be stored in a Redis database. In the default configuration of yuuvis® Momentum, the session state is stored by the individual AUTHENTICATION service instances. Thus, in order to enable the central storage of the session state in Redis, manual configuration steps are required.

Extend the authentication-prod.yml configuration file by the following lines:
```
spring.session.store-type: redis
management.health.redis.enabled: true
```
Add the redis profile to the AUTHENTICATION service:
- Run the command:
```
kubectl -n yuuvis edit deploy authentication
```
- Extend the SPRING_PROFILES_ACTIVE environment variable with redis.
Restart all instances of the AUTHENTICATION service.
- For example, instance 2 can be restarted using the following command:
```
kubectl -n yuuvis scale deploy authentication --replicas=2
```

Client Services & Client Development

SOTHOOK

Stability Improvement

The service uses the webhook type dms.request.objects.upsert.database-before instead of dms.request.objects.upsert.storage-before. With this improvement, the service can handle old objects with metadata properties that are no longer defined in the current schema. Furthermore, the SOTHOOK configuration is now part of the app-specific system hook configuration for the clientsystem app.

In your global system hook configuration, remove or disable the two webhooks with a value "http://sothook/*" for the "url" parameter. Add the following two webhooks to the app-specific system hook configuration, via the endpoint POST /api/system/apps/{app}/systemhooks for the clientsystem app.

Webhook array entries

{
    "enable": true,
    "predicate": "spel:T(java.util.List).of(100,101).contains(options['action']) && properties['system:secondaryObjectTypeIds'] != null && properties['system:secondaryObjectTypeIds']['value'].contains('appClientsystem:leadingType')",
    "type": "dms.request.objects.upsert.database-before",
    "url": "http://sothook/api/dms/request/import/databasebefore",
    "useDiscovery": true
},
{
    "enable": true,
    "predicate": "spel:T(java.util.List).of(300).contains(options['action']) && properties['system:secondaryObjectTypeIds'] != null && properties['system:secondaryObjectTypeIds']['value'].contains('appClientsystem:leadingType')",
    "type": "dms.request.objects.upsert.database-before",
    "url": "http://sothook/api/dms/request/updatemetadata/databasebefore",
    "useDiscovery": true
}

>> SOTHOOK

Artificial Intelligence Platform

ML Training Pipeline

New Model Response Format

The ML Training Pipeline uses MLflow 2.0 now. Thus, the response format is not compatible with models of the beta version that was available for previous yuuvis® Momentum versions. If you already trained some beta version models, you need to

update your system to yuuvis® Momentum 2022 Winter including the Docker images for the AI platform,
retrain the models and
rebuild your docker images that contain the retrained models.

yuuvis® Momentum

Update Instructions 2021 - 2022 Winter LTS

Table of Contents

Breaking Changes

Infrastructure

Support of Keycloak Version 19

Core

Performance Optimization for CONFIGSERVICE

Validation of Internal JSON Web Tokens

Tenant-specific Database Configuration

Client Services & Client Development

USERSERVICE

Migration of User Information Endpoints.

Service-specific Configuration

New Microsoft JDBC Diver for SQL Server

Developer Libraries

Angular Version Update

Task Properties in Inbox

Web-API Gateway

New Swagger UI Version

bpm-controller Endpoints

Business Process Managagement

BPM Engine

New Microsoft JDBC Diver for SQL Server

Tenant Management

Tenant Management API

New Swagger UI Version

idm-controller Endpoints

METRICS Service

Configurations Enabling new Features

Core

Fail-safe AUTHENTICATION Service

Client Services & Client Development

SOTHOOK

Stability Improvement

Artificial Intelligence Platform

ML Training Pipeline

New Model Response Format