What Is New in yuuvis® RAD 8.0

yuuvis® RAD 8.0 is the newest major version of our rapid application development tool for content-centric applications. It brings several new functions and technical improvements. Here is a brief overview:

• Update of WildFly for the core-service
• Update of the database drivers
• Update of Elasticsearch 
• Update of SpringBoot and SpringDoc for all services including the admin-service
  

Technical Improvements

We updated the WildFly application service as the basis of our core-service to version 26.

We updated the current drivers of the supported databases:

• Microsoft® JDBC Driver 10.2.0 for SQL Server 2019 and former versions
• PostgreSQL JDBC Driver 42.3.3 for PostgreSQL 13 and former versions
• ORACLEDB JDBC Driver 21.5.0.0 and former versions

We updated the search-service, index-service, and structure-service for Elasticsearch version 7.16.2 and the IntraFind Linguistik-Plugin 17.6.2. The installed Elasticsearch must be updated as well. 
Attention: A reindexing of all objects is necessary for this new Elasticsearch version. For your estimations: within one hour six to seven million objects are reindexed.

We updated all microservices to SpringBoot 2.5.7 version with SpringDoc and Swagger-UI, and adapted all services including the admin-service. In the future, we will waive the OS look and feel of the corresponding user interfaces here.
The name and icon of the service manager executable are changed now:

New Maintenance Features

• Our REST API supports the standard OpenAPI. This allows us to offer SpringBoot and Swagger for documentation and to try out the endpoints. Our REST-WS interface includes this Swagger-UI instead of the old UI.
• Developers can control whether DmsService.updateItem should validate non-existent reference objects. (internal: TUK-730)

User and Group Synchronization from Multiple LDAP Servers

• It is possible to synchronise users and groups from multiple LDAP servers.
• The authentication service can be configured to authenticate these users either with yuuvis® RAD managed passwords,
  or to be integrated with LDAP servers, so that they perform the authentication (thus allowing use of centralized password management for yuuvis® RAD).

New Features in yuuvis® RAD client including search-service

• Users can be informed about new tasks in their inbox by Windows notifications. (internal: TUK-747)
• Users are supported by an understandable error message if it is not possible to save an object when the value of a unique field already exists. (internal: TUK-21)
• Users can open the documentation with fewer clicks. (internal: TUK-875)
• Users can create a new object or update a document file by pasting a copied screenshot or a file into the browser while the client is focused. (internal: TUK-870)
• The performance of full-text searches with a beginning '*' is optimized based on a new Elasticsearch feature. (internal: TUK-849)
• Users working in an environment with context-path are redirected from an entered root-path to the configured context-path. (internal: TUK-830)

Deprecated Functions and Removed Features

• The ETL feature was removed entirely as it had been announced as deprecated with version 6.0. Keep in mind to switch from ERM to yuuvis® repository-manager 4.0 and migrate remaining ETL jobs to external applications like Talend jobs. If necessary, contact our yuuvis® consulting department for support.
• The pure user import (without groups) function in the user synchronization module is deprecated and will be removed in one of the future major releases. Customers can still use the user group synchronization.

Breaking Changes

• Due to the updated Spring Boot Admin UI the OPTIMAL SYSTEM services admin restart icons are no longer available on the dashboard. Instead, open the service detail view. In the menu, click on 'Control' and then 'Restart service' to restart the corresponding service. 
• Due to the update of the Gateway Service to Spring Boot 2.5.7 the configuration of the context path in the gateway-prod.yml file had to be changed. Therefore, the old configuration must be adapted after an update. Please also note the detailed update instructions: 
  Necessary Actions When Updating or Upgrading to 8.0
• Due to the integration of OpenAPI with Swagger UI, the old API test pages are no longer available.
• After the installation using the service manager setup, the old JKD8 files and directories are removed and the JDK11 artifacts are installed. Please also note the detailed update instructions: 
  Necessary Actions When Updating or Upgrading to 8.0
• Only 64-bit based custom microservices are supported. 32-bit based ones must be migrated.

During the development of yuuvis® RAD version 8.0, we focused on updates of relevant 3rd party components. Additionally, some new features and changes were made that are described in this documentation.

Updates

core-service

The core-service is now based on WildFly 26 and uses the latest database drivers. Therefore, this service has to be uninstalled first. The detailed update steps are documented here: How to Upgrade to yuuvis RAD 8.0

service-manager

All services are now based on JDK 11 and SpringBoot 2.5.x. The look and feel of the admin user interface has been changed as well as the Swagger-UI. The detailed update steps are documented here: How to Upgrade to yuuvis RAD 8.0

Elasticsearch update

The system now uses Elasticsearch version 7.16.2. So the Elasticsearch installation has to be changed. The detailed update steps are documented here: How to Upgrade to yuuvis RAD 8.0

Workflow Scripting Engine Was Changed

Starting with version 8, our workflow engine will switch from the Nashorn Script engine to the newer GraalVM engine. The new engine brings full support for the ECMAScript2 specification.

Since there are several syntactical differences with regard to scripts between Nashorn engine and in GraalVM/ECMAScript21, we recommend to test existing workflow models in version 7.16 (as described in the digest

 for 7.16) prior to upgrading to version 8, and if necessary to update the syntax of scripts to the new standard. 

Open API Support

Be aware of a different user interface: Due to the support of OpenAPI, the REST-WS interface offers a Swagger UI for documentation and test of the REST endpoints instead of the old user interface.

yuuvis® RAD designer

The new version of yuuvis® RAD designer requires .NET framework version 4.8.

yuuvis® RAD client

You can configure your client to offer the language German (Switzerland) with the iso code de-CH including the client language file de-CH.json. If this file is not available, the usual file de.json is used.
For information on how to configure this and which restrictions apply, please refer to our documentation (German version).

yuuvis® RAD repository-manager

There have been several technical updates:

• The required java version and the spring boot version have been updated to meet the requirements for servicemanger in version 8.0.
• The 3rd party component KGS contentserver has been updated to the latest version. This leads to an updated layout in the KGS-configuration GUI.

For more convenience: SAP-transports, used by consulting during the installation/configuration are delivered with the installation.
Timeouts for connect, write and read operations are configurable.

Deprecated Components and Endpoints

InboxService in core-service

The "InboxService" in the core-service with all its endpoints is deprecated and will be removed with version 9.0. The "inbox-service" microservice is to be used instead of all inbox features.

BpmService in core-service

The following endpoints are marked as deprecated and will be replaced by different endpoints with equivalent functionality that use HTTP verbs more consistently, provide clearer API, and reduce risk of erroneous use:

• POST /bpm/process/delete ("Delete all processes specified by the given IDs.", process IDs as request parameter)
• DELETE /bpm/process/ ("Delete all processes from specific process model.")

During the development of yuuvis® RAD version 8.2, the following new features and changes were made that are described in this documentation.

New Maintenance Features

yuuvis® RAD core-service – LDAP Synchronisation from Multiple LDAP Directories 

• This feature has been introduced in version 8.0 and has been now updated so that each user and user group synchronisation configuration can be placed in its yuuvis® RAD group (previously, users and groups from all LDAP directories would end up in the same yuuvis® RAD parent group). (internal: ERA-8619)

yuuvis® RAD service manager installation

• As an administrator, you are supported to set Elasticsearch parameters during the installation of yuuvis® RAD service manager. (internal: TUK-1051)

yuuvis® RAD agent installation

• As an administrator, you can easily roll out yuuvis® RAD agent with default connections. (internal: TUK-1044)

New User Features

yuuvis® RAD client

• German umlauts and emojis are correctly formatted in Excel, if a hit list export in CSV format is opened via double click. In order for this to work, the index service must be configured to set a UTF-8 BOM encoding. (internal: TUK-980)
• As a user speaking traditional Chinese (zh-Hant for traditional), Swiss German (de-CH), Thai (th), or Vietnamese (vi), you are potentially supported by the client user interface. Potentially means that an administrator can configure the client with the corresponding language files and that the dates and numbers are correctly formatted for these languages. In case of a sublocale like zh-Hant and de-CH, it is not possible to use them together with zh respective de because yuuvis® RAD designer only allows for the configuration of labels for the main locale which is used for the sublocales as well. (internal: TUK-1050)

Deprecated Functions and Removed Features

No features were set to deprecated or removed with version 8.2.

Breaking Changes 8.2

• The repository encryption is now disabled by default. The corresponding documentation is hidden. If you are already using encryption in a previous version, please contact OPTIMAL SYSTEMS Support to get an activation key and the documentation. (internal: TUK-938)
  • Beginning with 9.16 LTS Hotfix 3, the repository encryption can be used outside the European Union territory as well so we removed the key control and the feature can be used freely now.

During the development of yuuvis® RAD version 8.4, the following new features and changes were made that are described in this documentation.

Updates

Security

• All services use Spring Boot 2.5.13 to solve the CVE-2022-22950 issue. (internal: TUK-1033, TUK-1137, ERA-8647, ERA-8654, SAP-1193)

New User Features

yuuvis® RAD client

• Users are supported by a suggestion list when typing a value into a refrence field. This makes opening the suggestion dialogue unnecessary. (internal: TUK-1100)
• The object types displayed to users in suggestion lists of reference fields can be filtered by means of client form scripting.  (internal: TUK-1040)

yuuvis® RAD designer

• yuuvis® RAD designer can connect to a gateway with a configured context path. (internal: ERA-8502)
• It is possible to select system object types for the classification of IDs in DMS and workflow editor in order to be able to use them in a more general way than currently possible (only for abstract object types and object types). (internal: ERA-8412)

yuuvis® RAD management-studio

• Postponed to version 8.6: The complexity of user passwords can be configured in yuuvis® RAD management-studio. (internal: TUK-994)
• Postponed to version 8.8: Administrators are supported by an operation that extends the retention time for specific objects. (internal: TUK-862)

yuuvis® RAD core-service

• User and group synchronization from multiple LDAP servers can be configured such that all users and groups from each server are imported to specified groups in yuuvis® RAD. (internal: ERA-8619)
  • i.e., it is posible to specify the initialparent parameter for each domain that is synchronized in synchronization.domain.initialparent
  • top-level configuration (synchronization.initialparent) is inherited if single configuration does not specify it

Deprecated Functions and Removed Features

No features were set to deprecated or removed with version 8.4.

Breaking Changes 8.4

There are no breaking changes in version 8.4.

During the development of yuuvis® RAD version 8.6, the following changes were made that are described in this documentation.

Updates

Software Security

• The following remaining services use Spring Boot 2.5.13 to solve the CVE-2022-22950 issue: DMS-Sidecar, Rendition-Sidecar. As a result, DMS-Sidecar and Rendition-Sidecar do not use zuul any longer. If zuul is referenced in custom services when accessing DMS-Sidecar or Rendition-Sidecar, please delete the 'zuul' part from the URL. (internal: TUK-1137)
  

// before
<dmssidecarhost>:<dmssidecarport>/zuul/inbox

// after
<dmssidecarhost>:<dmssidecarport>/inbox

Password Security

• From now on, you have to observe simple rules when creating or changing user passwords. (internal: TUK-994)
  Existing passwords are not affected. The default rules are given below.
  When creating users or updating their passwords in yuuvis® RAD management-studio an error message is presented when the user data is saved and the password does not match the rules.
  When users change their password in the settings of yuuvis® RAD client, validation information is given for each rule that is not matched.
  The password rules can be set in yuuvis® RAD management-studio under System > Settings > Cluster > Session services > Password validation settings.
  Standard validation settings are:
  
  • Minimum length of user passwords. Default is 7 characters.
  • Minimum count of numbers. Default is 0.
  • Minimum count of special characters. Default is 0.

Deprecated Functions and Removed Features

Deprecated Methods Have Been Removed from $.http in Workflow Scripts

As announced in the digest of 7.16 LTS, deprecated methods have been removed from $.http.

We have originally planed and announced removal for version 8.0, but have decided to postpone it a bit, so that projects have more time to change and test the existing scripts.

Up to version 7.16 LTS, the scripts were using the singleton class HttpClient to execute HTTP calls. This semantic is error-prone because configurations of sequential HTTP requests could easily get mixed up unintendedly.
To improve this, a new HttpRequest class has been introduced with 7.16 LTS and the old one has been deprecated for removal. 

With version 8.6, the following methods in the HttpClient class (accessible via the $.http object) were removed:

• service()
• path()
• raw()
• header()
• param()
• query()
• body()
• clear()
• execute()

Beginning with version 7.16 LTS, the HttpRequest class is introduced in workflow scripting.

• Instances of HttpRequest can be created using these functions of the $.http object: get(), post, put, delete, patch.
• Instances of HttpRequest offer the following methods that are deprecated on HttpClient, such as service(), path(), body(), etc.

//prior to 7.16 LTS

this.$.http.get();
this.$.http.path("/service/organization/role/{id}").param("id", roleId); //This configures the http singleton. These methods on $.http are deprecated for removal in 8.0
var response = this.$.http.query("orgobjects", true).execute(); // This executes the singleton HttpClass.

//as of 7.16 LTS

var getRequest =this.$.http.get(); //This creates a new request instance.
var response = getRequest.path("/service/organization/role/{id}").param("id", roleId).query("orgobjects", true).execute(); //Configuration is executed on the getRequest object, no longer on the $.http singleton
//The methods for request instance configuration can be safely used in 7.16 LTS and onwards.

Breaking Changes

Deprecated methods have been removed from $.http in Workflow Scripts (see above for details).

During the development of yuuvis® RAD version 8.10, the following changes were made that are described in this documentation.

New/Changed Features

yuuvis® RAD client

The behavior of the folder title in the folder view has been enhanced. In the past, the title was always abbreviated even though there would have been enough space to show its entire length. This behavior was changed changed. Now the size of the tab itself increases for longer titles until there is no more space available. Only in cases were there is no more space available, the string is abbreviated. Note that you can always view the entire title in the metadata form.

During the development of yuuvis® RAD version 8.12, the following changes were made that are described in this documentation.

New or Improved Features

yuuvis® RAD core-service

• The template capability can be disabled/enabled in yuuvis® RAD management-studio in the same way other capabilities are configured (default is enabled). If the capability is disabled, the object type template is not offered for search in yuuvis® RAD client and no template objects can be created. (internal: TUK-1352)

yuuvis® RAD search-service

• The optimized expert search is now based on IntrafindQueryStringQueryBuilder. This enables better search results, especially for Asian languages. (internal: TUK-1304)

Deprecated Functions and Removed Features

No features were set to deprecated or removed with version 8.12.

Breaking Changes

There are no breaking changes in version 8.12.

During the development of yuuvis® RAD version 8.14, the following changes were made that are described in this documentation.

New or Improved Features

yuuvis® RAD search

• Search weighting does no longer distinguish between upper/lower-case letters. (internal: TUK-911)

REST-WS interface

• The REST-WS endpoints getOrganizationObjectById and getOrganizationObjectByName return the substitutes of users. (internal: TUK-1372)

yuuvis® RAD client

• User-specific changes to form table columns are now saved. (internal: TUK-1408)
• In the actions menu, the "More actions" area is now sorted alphanumerically. (internal: TUK-1416)
• Hebrew (he) is now supported in yuuvis® RAD client as a beta version which includes all date formats (e.g.. in the date picker) and numbers being displayed correctly.  There are still some issues with elements like tables that are not working well in right-to-left mode. (internal: TUK-1388)
• Users are informed about unsaved data when clicking outside the BPM start form to not lose changed data. (internal: TUK-1521)
• The performance of logging in yuuvis® RAD client has been optimized for many BPM models. (internal: TUK-1369)

yuuvis® RAD agent

• yuuvis® RAD agent no longer pops up after reactivating a workstation given that login was successful. (internal: TUK-1363)

Deprecated Functions and Removed Features

No features were set to deprecated or removed with version 8.14.

Breaking Changes

The OCR Service is now based on Finereader 12. It is necessary to update Finereader 11 to 12 and to exchange the license file as well.

During the development of yuuvis® RAD version 8.16 LTS, the following changes were made that are described in this documentation.

New or Improved Features

yuuvis® RAD client

• Users using only one monitor can configure the edit dialog of a form table such that it does not hide the viewer area. (internal: TUK-1298)
• When navigating back to the inbox via the browser's back button, the last task is set into focus. (internal: TUK-1373)
• The accessibility of the sidebar menu is optimized. Users can navigate with the tab key and the navigation does not leave the menu. (internal: TUK-1540)
• The client is now more secure. The found and reported CVE-2020-11022 issue was fixed. (internal: TUK-1338)
• The logo on the About page of yuuvis® RAD client can be changed by configuration similar to the logo in the app bar. (internal: TUK-1565)
• In the edit dialog of a form table, the checkbox status "Add additional row" is remembered for the specific form table so that users do not have to check it every time when opening the dialog. (internal: TUK-1572)
• When sharing a folder, users can decide whether to share only the folder or its children as well. The default is to share including the children as it was before this extension. (internal: TUK-713)
• A custom client can be configured to use all HTTP requests with the withCredentials parameter so that the given cookies can be transferred as well. This allows to integrate the a custom client into environments that use a different domain. (internal: TUK-917) 
• The logo on the login page can be exchanged via configuration. (internal: TUK-1643)

Workflow Scripting API Documentation

• Workflow scripting documentation has been restructured and moved to the server. It is available in the rest-ws pages of a running server.
• All classes available for workflow scripting are documented.
• Several tutorials explain how to use the available classes and their methods.
• This documentation replaces the old documentation (BPM Server-Side Scripting) which will no longer be maintained.
• The documentation is implicitly version controlled.

Deprecated Functions

• The BPM script API function HttpRequest:raw is deprecated and no longer necessary (can be safely removed from scripts). The function will be removed with version 9.0 and scripts can already be updated with 8.16 LTS as part of the update preparations.

Breaking Change

• With the hotfix service-manager 8.16.7, the index service will not take objects into account that contain tables with more than 20,000 rows. The reason for this limitation is caused by Elasticsearch which will throw an error while indexing such huge objects. This limitation can be changed in the index-service-prod.yml file (osfts.tableRowSize: 20.000). Increasing this limit will render the affected environment out of support.

Addendum

Hotfix dated May tbd, 2023

Need for action: In case your environment is configured to archive including retention dates, it could be that for some objects the date in the database deviates from the date that is set on the storage. With this hotfix the integrity check operation in yuuvis® RAD management-studio checks a given retention time and repairs found deviations.

Hotfix dated January 20, 2023

Single search terms are highlighted in the PDF-based preview. The first occurance of a search term is highlighted in green. All following occurances are highlighted in pink. The first occurance of the search term is also focused, no matter on which page of the document it is located. The search dialog of the PDF component is not opened immediately.

• the default is to share including the children as it was before this extension. (internal: TUK-713)
• A custom client can be configured to use all HTTP requests with the withCredentials parameter so that the given cookies can be transferred as well. This allows to integrate the a custom client into environments that use a different domain. (internal: TUK-917) 
• The logo on the login page can be exchanged via configuration. (internal: TUK-1643)

Workflow Scripting API Documentation

• Workflow scripting documentation has been restructured and moved to the server. It is available in the rest-ws pages of a running server.
• All classes available for workflow scripting are documented.
• Several tutorials explain how to use the available classes and their methods.
• This documentation replaces the old documentation (BPM Server-Side Scripting) which will no longer be maintained.
• The documentation is implicitly version controlled.

Deprecated Functions

• The BPM script API function HttpRequest:raw is deprecated and no longer necessary (can be safely removed from scripts). The function will be removed with version 9.0 and scripts can already be updated with 8.16 LTS as part of the update preparations.

Breaking Change

• With the hotfix service-manager 8.16.7, the index service will not take objects into account that contain tables with more than 20,000 rows. The reason for this limitation is caused by Elasticsearch which will throw an error while indexing such huge objects. This limitation can be changed in the index-service-prod.yml file (osfts.tableRowSize: 20.000). Increasing this limit will render the affected environment out of support.

Addendum

Hotfix dated January 20, 2023

Single search terms are highlighted in the PDF-based preview. The first occurance of a search term is highlighted in green. All following occurances are highlighted in pink. The first occurance of the search term is also focused, no matter on which page of the document it is located. The search dialog of the PDF component is not opened immediately.

Hotfix dated April 20, 2023

It is possible to disable the result list scoring. (internal: TUK-2223)
Modify the parameter osfts.modify-score in the configuration file search-prod.yml (default is true):

osfts:
  modify-score:
    false

Hotfix dated March 16, 2023

Shared objects are marked by an icon in the header of the object details. (internal: TUK-2197)

Hotfix dated March 1, 2023

Programmers can configure a custom queue for custom services (internal: TUK-1780). Refer to the following documentation for more information: Using the Messaging-Service.

Hotfix dated February 14, 2023

The extraction-service supports ZUGFeRD 2.2.

Administrators can configure the extraction-service to skip the EXIF analysis in case of performance issues. (internal: TUK-2008)
The EXIF analysis is skipped if this configuration is given in the extraction-prod.yaml file:

skipexif:
 extensions: "xml,xsd"
 threshold: 10MB

extensions must contain a list of extension shortcuts or "*" for each file
threshold is the size of the file in KB and MB for kilobytes and megabytes respectively. If no threshold is defined, all files with the specified extensions are skipped.

yuuvis® RAD repository-manager 4.3.1

Using Gateway and TLS/SSL for Secure DMS Connections

In addition to direct communication, the communication with the dms-service can be done using the gateway microservice. yuuvis® gateway also provides an option for secure communication with TLS. For this, yuuvis® gateway has to be configured.

Error Handling for Barcode Uploads

The  barcodeSentToR3 field will be set to true as soon as the document has been sent for processing regardless of the result of processing. (This was the behavior of yuuvis® repository-manager 3.) The object definition must be extended by an additional mandatory field: barcodeProcessingError.
If KGS reports an error, the system sets the value to true. This allows administrators to easily search for processing errors.

Please refer to the admin documentation for an updated example object definition

Logging Level Adaption

Logging of invoking of internal methods was changed from info level to debug level.

Necessary Actions When Updating/Upgrading

This page describes the actions that you must manually execute when updating from version 7.x to a newer version. It also lists things that you must pay special attention to. 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 the actions from your previous version to the target version in the order listed here.

• 7.16 --> 8.0

  • Manual steps are mandatory. See How to upgrade to yuuvis RAD 8.0 for a step-by-step guide.

• 8.4 --> 8.6

  • The license of the elasticsearch IntraFind-plugin expired on 07/01/2022 and needs to be renewed:
    • Stop Elasticsearch 7.16.2
    • Copy the file "license.jar" that can be found in the folder <setups>\elasticsearch to the folder "<elasticsearch7.16.2>\plugins\intrafind-linguistic" overwriting the existing one.
    • Start Elasticsearch 7.16.2 again.

• 8.10 --> 8.12

  • The password for the database connection of the core-service that is defined in the jas-app.xml file can now be stored in a credential store instead of saving it in plain text in the file.
    This is an optional feature. If you want to implement it, follow these steps:
    • Stop the core-service.
    • Create a credential store.
      • Open the file <core-service>\tools\change-db-pwd.bat
      • Replace all occurrences of @@CS_PASSWORD@@ with the same arbitrary password of your choice (for the credential store).
      • Save the file
      • Open a command prompt and change the directory to <core-service>\tools
      • Execute the following command:
        change-db-pwd.bat "databaseUserPassword" 
        Replace databaseUserPassword with the password of the user that connects to the database
    • Add the credential store to the jas-app.xml file and point the database connection password to it.
      • Open the <core-service>\standalone\configuration\jas-app.xml file.

      • Locate the <subsystem xmlns="urn:wildfly:elytron...> section and add the credential stores section to it as shown below. Replace "CS_PASSWORD" with your the credential store password chosen above.

        <subsystem xmlns="urn:wildfly:elytron...>     <credential-stores>         <credential-store name="dbcredstore" relative-to="jboss.server.config.dir" path="dbcredstore.cs" create="true">             <credential-reference clear-text="CS_PASSWORD" />         </credential-store>     </credential-stores>

      • Locate the <datasource jndi-name="java:/JASDB" ...>  section and replace the line <password>databaseUserPassword</password> with <credential-reference store="dbcredstore" alias="databasePW" /> as shown below.

        <datasource jndi-name="java:/JASDB" ...>     ...     <security>         <user-name>sa</user-name>         <credential-reference store="dbcredstore" alias="databasePW" />     </security>

    • Save and restart the core-service. 
      To change the password at a later time, execute the batch-file <core-service>\tools\change-db-pwd.bat.
      (Make sure the change-db-pwd.bat file does not contain any @@CS_PASSWORD@@ occurrences - if so replace them as described above.)

• 8.12 --> 8.14

  • With version 8.14 the OCR-Service was updated to use ABBYY FineReader 12. Therefore the existing installation of FineReader 11 must be removed and version 12 installed:
    • On the server hosting the OCR-Service, open the Windows uninstall Dialog and choose to uninstall FineReader 11.
      • If you can't find FineReader in the list of the applications, start the FineReader11 setup.exe installer. It will recognize that there already is an installation and ask whether to uninstall it.
    • Unzip the file Finereader12.4.7.63.zip from the setups directory and start installing FineReader 12 by executing the file setup.exe. 
      • When asked choose to license FineReader immediatly
      • When asked choose the Software Key License
      • When asked choose Production or Test license according to the server type you are installing to.
    • After the setup is finished copy the license file to the <FineReader12>\Bin and <FineReader12>\Bin64 directories.
    • Restart the OCR-Service if it is already running.
  • Updating yuuvis^® RAD repository-manager:
    
    • With version 4.2.x, a new KGS contentserver version has been integrated. Therefore, updating from version 4.1.x to 4.2.x the working-dir needs to be deleted.
      After installation, a new KGS-configuration is required.
      
      

• 8.14 --> 8.16

  • Updating yuuvis^® RAD repository-manager:
    
    • With version 4.3.x, the data model needs to be extended. There is an additional flag isBarcodeProcessingError which indicates errors during barcode processing.
      The extended schema is provided with the update and can be found after update in <rm-workdir>\obj-def. 
  • Context-Path settings
    • If using a custom context path, the file <service-manager-data>\webresource\resources\client\assests\_default\confiig\extend.json must be changed to only contain the parameter "contextPath": '/yuuvis' instead of all base addresses - as described here https://help.optimal-systems.com/yuuvisRAD/v80/admin/en/architecture/microservices/mic_tsk_install.htm?Highlight=context%20path

This guide describes how to install and configure a complete yuuvis® RAD 8.x system.

Where to Find the Installers

The official installers for the yuuvis® RAD 8.x release can be found in the OS cloud URL listed in the release e-mail.

Installation Process

Requirements

Also see the System Requirements (German version here).

• Microsoft SQL or PostgreSQL database server in one of the versions specified in the System Requirements (German version here).
• An exclusive database instance for yuuvis® RAD. 
  • The default language of the yuuvis® RAD DB user must be set to English. 
  • The user must be a local database server user. yuuvis® RAD does not currently support logging in the db with a domain user.
  • The user must have "db_owner" (or equivalent) rights on the yuuvis® RAD database instance.
  • The installation on a Microsoft SQL Server High Availability cluster is only possible by removing the yuuvis® RAD database from the cluster for the duration of the installation, then integrating it back into the cluster afterwards. This can be done while the cluster is online. Later updates of yuuvis® RAD do not require this process.
  • The starting size and "extend by" size of the data and log files should suit your needs. 
  • If the log file size is limited, the recovery model must be set to "simple".
• The server host names must conform with RFC 952. Specifically, they must not contain underscores ( _ ).
• The IP- and MAC-addresses must be static and cannot be changed.
• Firewall exceptions and/or proxy configurations/exceptions for all ports named in the System Requirements or configured differently to the setup's standard.
• Anti-virus exceptions for all folders used by yuuvis® RAD components.
• Microsoft .NET Framework version 4.6.2 for yuuvis® RAD designer.
• An evergreen browser (Chrome, Firefox, Edge) in the current version for the webclient.
• Microsoft Office in one of the versions specified in the System Requirements to run Office Add-In, Outlook Add-in (archiving) and yuuvis® RAD template-editor.
• We also recommend installing Notepad++, Baretail, and 7-Zip.
  
  

yuuvis® RAD core-service

• Start the setup by double-clicking, or, if you need to modify preset parameters, open an administrative command line and enter the setup command with the desired parameters.
• Follow the dialogs in the setup.
• Under the heading "Create database structure and base configuration":
  
  • Choose "yes" if you are doing a fresh install and the database is created but empty. This is the default.
  • Choose "no" if you already have an existing yuuvis® RAD database. This is the case if you are upgrading from a yuuvis® RAD 5.x installation or for example in disaster recovery situations.
• If you chose "yes":
  • Under the heading “Enter E-Mail Parameters" you may leave the parameters empty and enter them at a later time in yuuvis® RAD management-studio. 
  • The data directory will contain the WORK/CACHE/ARCHIVE area. You can configure the archive area separately after the setup (media management in yuuvis® RAD management studio).
  • Under the sidecar service URL, instead of localhost, you must enter the IP of the server hosting the service-manager. It doesn't matter whether or not the address or the dms-sidecar microservice can already be accessed. 
  • Note the systemuser API key. You will need to enter it during the service-manager setup.
• Start the installation.
• Immediately initialize the database. (This is only shown if you chose "yes" in the "Create database structure and base configuration" step)
• Do not start the service yet.
• If the database is an Oracle database:
  By default, the oracle schema name is equal to the upper case user name and this is used automatically.
  If you have the case / the requirement, that the schema name is different from the upper case user name, please configure it as follows:
  • Open the file <core-service>\standalone\configuration\standalone-full-ha.yml
  • Naviagte to the line "<subsystem xmlns="urn:jboss:domain:datasources:5.0">" and there to "<datasource jndi-name="java:/JASDB"..."
  • Within this section, add the following new line under the line beginning with "<connection-property": <new-connection-sql>ALTER SESSION SET current_schema=schemaname</new-connection-sql>
    Replace 'schemaname' with the name of the schema. (Do not use any quotation marks.)
• Modify the data directories (optional) :
  • For optimal configuration of the media sets please see: Configuring Media settings for Optimal Harddisk and Inode Usage
  • The JBoss data and temp directories can be configured using the JVM-options jboss.server.data.dir and jboss.server.temp.dir.
  • WORK / CACHE / ARCHIVE can be configured in the management-studio (menu entry Media) after the core-service and the service-manager have successfully started. 
• Modify the log directory (optional) :
  • In the directory <core-service>\bin, run the yuuvis_rad_core-servicew.exe file:
    • In the Logging tab, change the log path and if desired, change the routing for stdout and stderr.
    • In the Java tab, in Java Options, modify the values for -Djboss.server.log.dir and -Dorg.jboss.boot.log.file
• Change the service-user (optional):
  • Run the "yuuvis_rad_core-servicew.exe" file in the <server>\bin  directory.
  • Enter the technical (Windows) user in the "Log On" tab.
• Change the heap-space settings (optional):
  • Run the "yuuvis_rad_core-servicew.exe" file in the <server>\bin  directory.
  • In the "Java" tab, modify the "Maximum memory pool" value to the desired maximum amount of working memory for the core-service (see the System Requirements for recommendations).
• Start the service.
• Check the log file <core-service>\logs\core-service.log with a logging program such as Baretail for the successful start of the service. The service has been successfully started when a large "yuuvis" logo is displayed as ASCII art.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

yuuvis® RAD designer

• Start the setup by double-clicking.
• Follow the dialog boxes in the setup.
• Complete the setup.
• You can configure and manage connections to the core-services in the designer under Settings > Connections.
• Modify the log directory:
  • In the root directory of designer, open the logging.nlog.config file in a text editor and modify the value in the following line:
    "<variable name="logDirectory" value="${specialfolder:folder=LocalApplicationData}\OPTIMAL_SYSTEMS_GmbH\Logs\enaio designer" />"
    
    

The setup MSI supports the following parameters:

Elasticsearch

• Start the setup by double-clicking.
• Follow the setup dialogs.
• Under HTTP-Port, you can configure the port that Elasticsearch will listen on. This port should only be changed if the default port (9200) is already being used. For more details see below.
• The index directory is the directory where Elasticsearch will put its index (database) files. This directory can become very large. We recommend to use SSD storage for this directory.
• When asked for the maximum memory, configure the amount of heap space that Elasticsearch can use. This should be between 4 and 31.5 GB.
• Start the installation.
• Do not start the service yet.
• Change the http and transport ports (optional unless running 2+ instances on the same machine):
  • Edit the <elasticsearch>\config\elasticsearch.yml file
  • Change the "http.port:" property to your desired port. Make sure to reflect this change in the <service-manager>\config\application-es.yml configuration file of the service-manager.
  • Change the "transport.port" property to your desired port
• Set the repository path (optional, if no cluster is set up):
  • Edit the <elasticsearch>\config\elasticsearch.yml file
  • Edit the "path.repo:" property and set your desired repository path. Use "/" instead of "\" in the path.
    If you want to run Elasticsearch in a cluster, this path needs to be used by all cluster nodes and therefore it needs to be accessible by all cluster nodes.
• Modify the service user (optional):
  
  • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
  • Enter the technical (Windows) user in the "Log On" tab.
• Change heap space settings (optional):
  • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
  • In the "Java" tab, modify the "Maximum memory pool" value to the desired amount of heap space for the service. Make sure "Initial memory pool" is set to the same value.
  • In the "Java options" section adapt the "-Xmx" and "-Xms" settings to the desired amount of heap space.
• Modify the data directory (optional):
  • Edit the <elasticsearch>\config\elasticsearch.yml file
  • Edit the "path.data:" property and set your desired data path. Use "/" instead of "\" in the path.
• Modify the log directory (optional):
  • Run the "elasticsearch-793-service-x64w.exe" file in the <elasticsearch>\bin directory.
  • Modify the log directory in the "Logging" tab.
  • Edit the file <elasticsearch>\config\elasticsearch.yml
  • Add a line with "path.logs: " and the path to your desired logs folder. Use "/" instead of "\" in the path.
• Start the service. (check es-red.log file in the logs folder for correct startup)
• Execute the <elasticsearch>\bin\elasticsearch-set-initial-passwords.bat file
• Copy the password of the 'elastic' user. (Alternatively, you can open the <elasticsearch>\config\built-in.usr file and look it up there.)

yuuvis® RAD service-manager

• Double-click to start the setup.
• Follow the setup dialogs.
• Under HTTP-Port, you can configure the service-manager services port. This port has no special significance but should only be changed if the default port (7281) is already being used.
• Under "Enter yuuvis® RAD core-service parameter", enter the IP address of the server that hosts the core-service.  
  Also enter the systemuser API key that you noted during the core-service setup.
• Under "Enter database parameter" at "database server" enter the IP address under which the database used for yuuvis® RAD (core-service) can be reached. You may need to modify the port (1433 is generally correct for MSSQL databases).
  Also enter the database name of the database used for the yuuvis® RAD (core-service), as well as the credentials of the database user designated for yuuvis® RAD into the corresponding fields.
• Under "Enter enaio rendition-plus parameter", enter the IP address and the port of the server that hosts yuuvis® RAD rendition-plus. Rendition-Plus does not yet have to be installed. If a different port is selected during installation of Rendition-Plus, you must enter it instead of the default 8090.
• Under "Configuration of Elasticsearch" enter the IP(s) and port(s) of the elasticsearch servers, the password of the 'elastic' user that was generated when executing the file <elasticsearch>\bin\elasticsearch-set-initial-passwords.bat and the language code for the language that the Intrafind linguistic plugin should support. The language code can be one of the following values: de,en,es,fr,it. Set the language code of the language that is used the most in your system. All other languages active in your system will have basic support. Attention: only one value may be set to this parameter.
• Under "IP Filter for dms-sidecar", enter the IP addresses and/or IP address ranges that should get access to the dms-sidecar. The dms-sidecar provides access to the core-service REST-WS API and thus access to it should be limited to the necessary servers only. The value is a regex expression, refer to this page for more details.
• Complete the setup but do not start the service yet.

• If the structure-service and the discovery-service are on different machines and/or the discovery-service is running on a port different than the standard (7261), edit the file <service-manager>\config\servicewatcher-sw.yml and add the "env" parameter with the corresponding values (host and/or port of the discovery-service) to the section of the structure-service as follows:

  - name: structureservice   type: executable   profiles: prod,red,es,mq   instances: 1   port: 7461-7469   path: ${appBase}/structureservice/structure-service.exe   env:     EUREKA_HOST: 10.10.1.2     EUREKA_PORT: 9261

• The following settings are optional:
  
  

  • If you are setting up a productive system and expect to have a very high amount of documents (i.e. > 50 Mio. documents) and/or data in elasticsearch (many metadata fields and/or big fulltexts) consider increasing the number of shards from 1 (the default) to a more appropriate one. If you have more than one node in your elasticsearch cluster, use at least the number of nodes as the number of shards. We do not recommend to go higher than 3 or 4 times of the number of nodes as this would rather lower the performance again. See also https://www.elastic.co/guide/en/elasticsearch/reference/current/size-your-shards.html for more details.
    To increase the number of shards, edit the file <service-manager>\config\index-prod.yml and add the line shown below. This must be done before the first start of the service-manager (index-service) to take effekt (otherwise a reindex using the index-service's swagger-ui endpoint is necessary).

    osfts.number-of-shards: 3

  • Change the rollover settings for the logfiles:

    • Open the file "<service-manager>\config\servicewatcher-sw.yml" and complete the logging section as shown below.

      logging:    file: ./../../logs/services.log    config: ./config/logback.xml    maxDays: 30    totalSizeCap: 10GB

      The parameter maxDays determines for how many days a log file should be saved.
      The parameter totalSizeCap limits the total size of all log files to the specified value.
      
      

  • Define gateway authentication method and custom endpoints:

    • In the "<service-manager>\config\gateway-prod.yml" file, you can adjust the authentication mechanism for the services by setting the "authentication.filter.*" properties as follows:

      • Basic-authentication:\ntlm: false, form: true, basic: true
      • NTLM (SSO) authentication: ntlm: true, form: false, basic: false
        
        

    • You can also define additional (external) endpoints as follows:

      routing.endpoints name: 'custom' url: 'http://localhost:4321'

  • Modify the data directories:
    • In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.
    • In the "Java" tab, under Java Options, set the temp directory with the JVM option Djava.io.tmpdir. You can use the options –Dcatalina.base and –Dcatalina.home to set the Tomcat work directories.
    • In the directory <service-manager>\config, open the application-prod.yml file and modify enaio.data.path. The relative path to the .jar files is <service-manager>\apps\<*service>. If you use './../..', you end up in the service-manager root directory.
  • Modify the log directory:
    • In the <service-manager>\bin directory, run the enaio_red_service-managerw.exe file.
    • In the "Logging" tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.
    • In the "Startup" tab, modify the "--logging.file" argument. The relative path to the .jar files is under <service-manager>\apps\<*service>. Use './../..' to point to the service-manager root directory.
    • In the <service-manager>\config, open the servicewatcher-sw.yml file and in the "logging" section, modify "file". The relative path to the .jar files is under <service-manager>\apps\<*service>. Use './../..' to point to the service-manager root directory.
  • Modify the service user:
    
    • In the <service-manager>\bin directory, run "enaio_red_service-managerw.exe".
    • (Optional) In the "Log On" tab, enter the technical (Windows) user.
• Start the service.
• You can see an overview of the running services at http://<ip>:7273. This is the Spring Boot Admin service. It can be used to permanently monitor the services.
• It can take several minutes for all the services to start successfully.
• "Connection refused" exceptions appearing in the service-manager log file in the first few minutes are nothing to worry about.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

 
yuuvis® RAD rendition-plus

• Start the setup by double-clicking.

• Follow the dialogs in the installer.
• The HTTP port determines through which port the rendition-plus service can be contacted. If you deviate from the default 8090, you must modify the service-manager configuration file application-red.yml accordingly.
• In "enaio Rendition sidecar" enter the IP address of the server hosting the service-manager. Important: 127.0.0.1 is only valid if both services are installed on the same machine. If not, you must use the externally visible IP address.
• Complete the setup but do not start the service yet.

• In the file <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\config\config.properties, modify the maximum size of the rendition cache with the cache.maxsize parameter if the preset of 500 GB does not fit your needs. The smaller you make the cache size, the more often existing rendition files are displaced and have to be created again when requested by a call.

• Modify the data directories (optional):
  • In the <rendition-plus>\bin directory, run "enaio red rendition-plusw.exe".
  • In the "Java" tab, under Java Options, set the temp directory with the JVM option -Djava.io.tmpdir. You can use the options –Dcatalina.base and –Dcatalina.home to set the Tomcat work directories.
  • In the file <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\config\config.properties, you can modify rendition-cache specific data directories.
    • To modify the Cache directory, use the sor.root key.
    • To modify the Jobs directory, use the job.root key.
    • To modify the Temp directory, use the temp-base key.
    • To modify the Database-Root directory, use the db.root key.
  • In the file <rendition-plus>\webapps\renditionplus\WEB-INF\classes\config\config.properties, you can modify rendition-plus specific data directories.
    • The temp directory can be adjusted by the temp-base key.
• Modify the log directory (optional):
  • In the <rendition-plus>\bin directory, run "enaio red rendition-plusw.exe".
  • In the "Logging" tab, modify the log path and, if desired, set up or change the redirects for stdout and stderr.
  • In the <rendition-plus>\conf directory, open the logging.properties file and modify all lines that correspond to a *.directory key. (As a rule, $(catalina.base) corresponds to the rendition-plus root directory.)
  • Open the <rendition-plus>\webapps\osrenditioncache\WEB-INF\classes\log4j.properties file in a text editor.
    • Modify the log4j.appender.OsRenditionCacheLogFile.File key to change the path of OsRenditionCacheLogFiles.
    • Modify the log4j.appender.JobMonitoringLogFile.File key to change the path of JobMonitoringLogFiles.
  • Open the <rendition-plus>\webapps\renditionplus\WEB-INF\classes\log4j.properties file and modify the log4j.appender.RenditionPlusLogFile.File key to change the path of RenditionPlusLogFiles.
• Modify the service user (optional):
  
  • In the directory <rendition-plus>\bin, run the "enaio red rendition-plusw.exe" file.
  • (Optional) In the "Log On" tab, enter the technical (Windows) user.
• Start the service
• Check the log files for correct startup and/or check the service-manager admin (http://<service-manager-ip>:7273) if the renditionsidecar is available.

The setup can be run using the command line. Use the --help option to see a list of all available parameters and options.

yuuvis® RAD agent, yuuvis® RAD Office  Add-in,  yuuvis® RAD Outlook Add-in and yuuvis® RAD template-editor

• Start the MSI Setup by double-clicking it.
• Other than an installation path, the setups need no additional input and complete on their own.
  If you are installing the MSIs using the console (e.g. Microsofts software distribution) you can specify the parameter "installdir" to change the default installation path.
• Modify the Log Directories:
  • The log directories cannot be modified at this time.
  • Log files for the add-ins can be found in %LOCALAPPDATA%\OPTIMAL_SYSTEMS_GmbH\Logs, in the corresponding subfolders.
  • Log files for the agent can be found in %APPDATA%\enaio red agent\logs.
    
    

yuuvis® RAD metrics-manager

• Please refer to the metrics-manager Installation Guide.

For security reasons, the passwords for the system accounts should be changed after the installation is complete.