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.

Preview - 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)

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

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

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

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