Each yuuvis® Momentum version update introduces changes in the system. In general, we try to deploy such changes in a non-breaking way. If this is not possible, you will find all necessary and vital information on this page. 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. An update to a new version that skips some of the previous versions is possible and does not require updating to each version in between. However, in this case, you must carry out all actions in the order in which they are listed below. Starting with your current version up to the version you want to update to.

Product Version 2023 Winter

Please refer to our new documentation format:
>> Breaking Changes

Product Version 2023 Autumn (as of August 23, 2023)

Infrastructure

Support of Keycloak Version 22

Keycloak version 22 requires the scope configuration parameter. The Keycloak update is optional for the core system, but MANDATORY for

• Tenant Management API and
• KEYCLOAK-PROXY Service.

>> yuuvis® Momentum Requirements

Action: Configure the scope parameter in the application-oauth2.yml configuration file.

Core

Support of multiple Elasticsearch Instances

To realize high performance while the workload increases, it is now possible to configure multiple Elasticsearch instances. Furthermore, the connection to Elasticsearch can now be secured by username and password.

Action: To continue using the same Elasticsearch instance for all tenants, replace the spring.data.elasticsearch parameters as shown in the example below in your application-es.yml configuration in the Git root directory.

• The spring.datasource parameters used up to product version 2023 Summer:

  spring.data.elasticsearch.cluster-name: 'my-es-cluster'
  spring.data.elasticsearch.cluster-nodes: '12.23.5.678:9012'
  spring.data.elasticsearch.repositories.enabled: true

• The new configuration structure used as of product version 2023 Autumn:

  storage:
      searchdatabases:
        database1:
          datasource: dbsource1
          predicate: 'spel:true'
          default: true
          
      searchdatasources:
        dbsource1:
          urls: '12.23.5.678:9012'
          index: 'exampleindex'
  

To use different Elasticsearch instances for individual tenants, please read the documentation of the application-es.yml configuration file.

Product Version 2023 Spring (as of March 03, 2023)

Core

New Metrics Endpoints

The AUDIT service requires a Redis connection now. If you use the Helm Charts for your version update, your configuration is automatically adjusted and thus you do not need the following action.
Action: Restart the AUDIT service with the redis profile.

greedy Parameter for Batch Deletion

The DELETE /api/dms/objects endpoint's response is different even in the default request with greedy=false.

Client Services & Client Development

Web-API Gateway

New idm-controller

The following endpoints were moved from the user-controller to the new idm-controller. They are scheduled to be permanently removed with the next product version.

Action:

Update the access configuration for the individual endpoints of the Web-API gateway in the authentication-prod.yml configuration file. The example code block shows the new default configuration for new installations.

### api-web  
  - endpoints: /api-web/swagger-ui.html,/api-web/swagger-ui/**,/api-web/**/v3/api-docs/**
  - endpoints: /api-web/api/system/**
    access: hasAuthority('YUUVIS_SYSTEM_INTEGRATOR')
  - endpoints: /api-web/api/admin/**
    access: hasAuthority('YUUVIS_TENANT_ADMIN')
  - endpoints: /api-web/api/dms/**,/api-web/api/bpm/**,/api-web/api/resources/**,/api-web/api/users/**,/api-web/api/idm/**

Business Process Management

BPM Engine

Filtering of Task Lists

The GET /bpm-engine/api/tasks endpoint for the retrieval of a task list now accepts the boolean query parameter isAssigned instead of filter.
Action: Adjust your requests considering following behavior:

• If isAssigned=true, the endpoint retrieves only tasks that are assigned to the currently logged-in user.
• If isAssigend=false, the endpoint retrieves only tasks without an assignee for which the currently logged-in user is a candidate user.
• If isAssigned is not specified in the request URL, the endpoint retrieves tasks that are assigned to the currently logged-in user as well as tasks without an assignee for which the currently logged-in user is a candidate user.

Product Version 2022 Winter (as of December 05, 2022)

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

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 any longer. 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 LTS:

  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

Developer Libraries

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

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.

Tenant Management

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.

Product Version 2022 Autumn (as of August 29, 2022)

Client Services & Client Development

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 change has been subsequently added to the version. See Breaking Changes 2022 Winter.

Web-API Gateway

bpm-controller Endpoints

The change has been subsequently added to the version. Breaking Changes 2022 Winter.

Tenant Management

Tenant Management API

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.

Product Version 2022 Summer (as of May 13, 2022)

Core

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.

Product Version 2022 Spring (as of February 22, 2022)

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

Client Services & Client Development

Developer Libraries

Object Creation Permissions

The permission to create new objects is now enabled via a create permission within one of the roles defined via a role set. The YUUVIS_CREATE_OBJECT role does no longer allow object creation. You need to adjust your corresponding role set accordingly.

Action: Update your roles as described here. Use the following condition:

<condition>system:objectTypeId = 'appClient:minidoc' AND system.secondaryjectTypeIds = 'appClient:minidoc'</condition>

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/**
  ...
...

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.

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/**
  ...
...

Product Version 2021 Winter (as of November 12, 2021)

Core

Performance Optimization for CONFIGSERVICE

Local and remote resources on the git server are synchronized now at regular intervals of 5 minutes. Thus, changes applied directly to the remote resources on the git server are NOT available until the regular synchronization process is passed. The resources are always cached. The availability of the git server is not checked anymore in case of resource retrieval requests. It is no longer possible to set the parameter fail-if-git-not-available=true.

Furthermore, the Helm Charts create a persistent volume claim for each CONFIGSERVICE instance that will be used for service initialization after a service restart.

In case multiple instances of the CONFIGSERVICE are running, the synchronization of the individual local resources is done at regular intervals of 5 minutes as well. Thus, requests for resources that have been modified less than 5 minutes ago might lead to the retrieval of a deprecated version of those resources. Resources created less than 5 minutes ago might be not available.

Client Services & Client Development

Developer Libraries

BPM Integration in Clients

In order to provide the new features in client applications, the BPM process model follow-up has been updated. Process instances based on the previous version of the follow-up process model are not anymore supported. They are displayed without subject and attachments.

Action: You can delete those process instances via the client application or via the corresponding Web-API Gateway endpoint.

Management of Configuration Files

• In order to unify the management of standard configurations, the standard column and filter configurations are now managed via the Web-API Gateway and no longer via the USERSERVICE.
  
• All client-specific configuration files like main, plug-in or language configuration are managed via the Web-API Gateway as well.

Action:  If standard column or filter configurations are already stored in your system via the USERSERVICE, they need to be imported again via the corresponding Web-API Gateway endpoint.

Product Version 2021 Autumn (as of August 20, 2021)

Core

Token Handling for Custom Services

The internal tokens (JWT) created by the AUTHENTICATION Service are now signed.

Actions:

• If you are working with Java custom services using the annotation com.os.services.core.security.EnableServiceSecurity from the library services-security, you need to update the library to version 5.7.0.
• If you are working with Java custom services using the library com.nimbusds:nimbus-jose-jwt for parsing of incoming JWTs, you have to use the class com.nimbusds.jwt.SignedJWT instead of the class com.nimbusds.jwt.PlainJWT.
  
  

Object Creation Permissions

In role sets, permissions can now be set for the creation of objects by introducing the action create. So far, the object creation was enabled together with the edit permission via the action write. Additionally, the role YUUVIS_CREATE_OBJECT had to be assigned to users in order to enable object creation via API Gateway. As of now, this role does not affect the functionality of the API Gateway and is not part of the global default role set anymore. 
>> Access Authorization and Permissions

Actions:

• In each of your existing role sets, add <action>create</action> to each permission including a write action that should allow for object creation further on. If the permission includes a condition, ensure that no CONTAINS statement is involved. Use the endpoints for managing permissions.

• Remove the following lines from section ### API-endpoints in authorization.accesses in the configuration file authentication-prod.yml:

  - endpoints: /api/dms/objects
    method: POST
    access: hasAuthority('YUUVIS_CREATE_OBJECT')

Tenant Management API

Assignment of the System Integrator Role

In previous versions, the endpoint POST /tenant-management/api/admin/users that is accessible with the role YUUVIS_TENANT_ADMIN allowed for the assignment of the role YUUVIS_SYSTEM_INTEGRATOR to other users. This is not possible anymore. Only the endpoint POST /tenant-management/api/system/tenants/{tenant}/users that is accessible with the role YUUVIS_SYSTEM_INTEGRATOR allows for the assignment of the role YUUVIS_SYSTEM_INTEGRATOR to other users.

Developer Libraries

No Printing via 'ContentPreviewComponent'

The ContentPreviewComponent provided by the framework library does not allow for printing anymore. Users have to download the binary content files and print them from their local drives.

Product Version 2021 Summer (as of May 28, 2021)

Web-API Gateway 

URLs (as of Release Candidate Alpha5)

The endpoint URLs have been changed to match the structure of other service-specific endpoint URLs. The new URLs are used by yuuvis® client as reference implementation and yuuvis® architect.

Action: If you are already referencing one of the following endpoints in your applications, please update the corresponding URLs. See also Update Instructions 2021 Summer.

Product Version 2020 Winter (as of March 05, 2021)

Elasticsearch Index

Queriable Tables

Using a new Elasticsearch index structure for tables, single table cells can be accessed in search queries. Tables indexed for Elasticsearch with the former format are still accessible in the system, but not by means of single-cell search queries.

Action: If you have already been using table properties in your system, please reindex them by means of the COMMANDER service. The process can run in the background, the operation of the system does not have to be interrupted. Use the command dbs-reindex Command. The reindexing will also apply to every tag in the system.

Tagging

Storage Format of Tags

The internal storage format in the Elasticsearch index was changed for tags, since they need to be stored in the new table format as well.

Action: If you have already been using tags in your system, please reindex them by means of the COMMANDER service. The process can run in the background, the operation of the system does not have to be interrupted. Use the command dbs-reindex Command. The reindexing will apply also to every queriable table property assigned to any stored object.

Tag Name Validation

Tag names are now validated during a tag creation or update process. To pass the validation, they have to match the regular expression [a-z](:?[a-z][a-z0-9]*)* and must not be longer than 32 characters.

Action: Please check your used tag names and replace any used capital letter by a lowercase letter.

Schema Validation

Table Column Names

In order to allow for single-cell search in tables, table column names must not have a prefix in their property definition in the schema. The schema validation will no longer accept a schema containing table column names with prefixes.

Action: Please update all column names of table properties accordingly in your sources.

yuuvis® client as reference implementation / yuuvis® architect

According to the new indexing of table properties, the endpoints for getting a schema definition provide table column names without any prefix. Especially if the table property is defined in a tenant schema or in an app schema, the table column names will also not have any prefix. Since the reference client uses the exact value of table columns for localization, form modeling and scripting, changes have to be adopted.

Action: Please remove the prefixes from table column names referenced in the localization, in forms and in scripts.

Product Version 2020 Autumn (as of October 30, 2020)

yuuvis® client as a reference implementation

Schema definition

All of your document object type definitions used in the client must have a static reference (static="true") to the secondary object type appClientsystem:leadingType. The type comes with a reference to appClientsystem:leadingTypeId property and is defined in our newly delivered app schema Clientsystem. 

The property (field) is used to handle the transformation of a document object type during its lifecycle:

• In case of regular document object types with a static reference to this secondary object type the value contains the value of system:objectTypeId.
• In case of document object types with a floating reference to a secondary object type for a classification(static="false") at later point in time, their object type IDs are assigned as leading type

The values are set for each update by the new sothook, which has to be installed and configured. It writes the current leading object type IDs into the property.
>> "Referencing the 'appClientsystem:leadingType' Object Type" | "/wiki/spaces/YMY/pages/320053918"

Permissions

In Keycloak, you have to assign the new 'YUUVIS_CREATE_OBJECT' role  to all users who need to be able to create new objects.
>> "Access Authorization and Permissions"

API-WEB microservice

The Search Service API supports rapid development of custom clients and is part of the API-WEB service. It is used by our reference implementation: yuuvis® client. The API has been changed and a query's result is now an array instead of an object. 
>> "Search via Web-API Gateway"

Product Version 2019 Winter (as of December 13, 2019)

Renaming of system properties from "enaio" to "system"

The API comes with a personal, tenant-specific schema, which consists of unchangeable system properties, and the global schema. It determines the attributes and properties that objects must or may have. Our system properties have been renamed from "enaio" to "system".

Example: System properties enaio:objectId, enaio:createdBy and enaio:creationDate have been renamed to system:objectId, system:createdBy and system:creationDate.

Action: Please update all used system properties accordingly in your sources.
>> Schema

Schema version has been updated to 5.0

Your personal, tenant-specific schema consists of unchangeable system properties and the global schema. It determines the attributes and properties that objects must or may have. 
You can retrieve your schema by sending a GET request to the URL /admin/schema ("Get the raw tenant schema" endpoint) and bring in your schema modifications update using
POST request to the URL /admin/schema ("Update the tenant schema" endpoint).

Note that the schema's version has been modified from 4.0 to 5.0.

<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/" ...

Action: If you are going to update a schema, make sure that you use the new version number 5.0.
>> Admin Endpoints