Version-dependent patch steps

To upgrade to the desired version, you must perform all applicable patch steps from the following list whose patch level is higher than the current patch level and lower than or equal to the target version.

For example, if you want to upgrade to the target version 8.0.18 and your current version is 8.0.3, you must complete all steps from patch version 8.0.4 up to and including patch version 8.0.18.

In case a patch step occurs several times, you must execute it once only (e.g., Tomcat updates).

List structure

  • Patch level

    Patch level requiring a manual patch action. Patching is necessary if you patch from a minor version to the indicated or to a higher version.

  • Prerequisites

    Conditions that must be met for you to perform the patch step manually.

  • Action/Proceed as follows

    Action(s) that must be performed.

8.1.0

Only standard patch steps are required.

8.1.1

Only standard patch steps are required.

8.1.2

Enable HTTPs TLSv1.3 by default

Action

Only the versions TLSv1.2 and TLSv1.3 are currently classified as secure.

To enable the latest TLS version on both the server and client side, configure the settings so that only TLS 1.2 and TLS 1.3 are supported.

Proceed as follows

  • The values for -Dhttps.protocols=…​ have been adjusted:

    • New (recommended) value: -Dhttps.protocols=TLSv1.2,TLSv1.3

    • BUT: This may cause HTTPs connections between the Process Engine and other servers that rely on older TLS versions to no longer work.

  • The values for -Djdk.tls.client.protocols=…​ have been adjusted:

    • New (recommended) value: -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3

  • Check the values in the following files and adjust them accordingly:

    <inubit-installdir>/inubit/server/process_engine/bin/setenv.[bat|sh]
<inubit-installdir>/inubit/bin/start_workbench.[bat|sh]
<inubit-installdir>/inubit/server/process_engine/bin/startcli.[bat|sh]
<inubit-installdir>/inubit/client/bin/start_workbench.[bat|sh]
<inubit-installdir>/inubit/client/bin/startcli.[bat|sh]

  • Also use the files created by the patch installer with the suffix _patch.[bat|sh] to access the file contents recommended by Virtimo AG.

After completing the above steps, restart the Process Engine and Workbench.

Impacts:

  • Application - Process Engine

  • Application - Workbench

8.1.3

Upgrade Keycloak to version 26.0.x

Prerequisites

You are already using Keycloak as an identity provider for INUBIT.

Action

Upgrade Keycloak and the corresponding client library in INUBIT to version 26.0.1 The Keycloak upgrade is not backwards compatible and therefore both the Keycloak application and the data stored in the database must be migrated.

Proceed as follows

  1. Read Keycloak Migration Guide to learn about the latest migration changes.

  2. Stop the Keycloak server if it is running.

  3. Read Preparing for upgrading and follow the preparation steps.

  4. Run the Virtimo Digitalization Suite patch installer and upgrade to the latest Keycloak version on your computer.

  5. Read Migrating the database and follow the database migration steps.

  6. Read the remaining sections like Migrating themes and follow the instructions.

  7. Start the Keycloak server.

  8. Login to Keycloak admin console and navigate to Realm Settings and change the value of "Unmanaged attributes" to "Enabled".

  9. Navigate to Authentication and then to Required Actions tab.

  10. Change the value of "Verify Profile" to "off".

Impacts:

8.1.4

AS4 log file path

To place the as4gateway.log file under <inubit-installdir>/inubit/server/ibis_root/log.

Action

  1. Stop the Process Engine

  2. Change the following entry to <inubit-installdir>/inubit/server/ibis_root/conf/as4/log4j2.properties and specify the absolute path to the target folder where the as4gateway.log file should be created:

    # Log into <inubit-installdir>/inubit/server/ibis_root/log
property.basePath=${env:CATALINA_BASE}/../ibis_root/log

  3. Save all changes

  4. Start the Process Engine

Impacts:

Configuring the Log Cleanup Service under Windows

Prerequisites

The patch installation has been performed.

Proceed as follows

  1. Set up the required scripts

    1. Save the script file ibis_nt_service_nssm_install.cmd.

    2. Rename the file ibis_nt_service_nssm_install_patch.cmd to ibis_nt_service_nssm_install.cmd.

    3. Save the script file ibis_nt_service_nssm_uninstall.cmd.

    4. Rename the file ibis_nt_service_nssm_uninstall_patch.cmd to ibis_nt_service_nssm_uninstall.cmd.

  2. Installing the service

    1. Run the ibis_nt_service_nssm_install.cmd script to install the service.

      When installing the INUBIT Process Engine as a service via the ibis_nt_service_nssm_install.cmd script, a new service called LogCleanupService is additionally installed and started automatically. This service is configured to run the log_cleanup.cmd script, which contains the logic for log cleanup.

      The log_cleanup.cmd script calls the pe_log_cleanup_conf.bat configuration file, which defines the following variables:

      • MAX_FILE_COUNT: Specifies the maximum number of log files to keep. Defaults to 10.

      • MAX_AGE_DAYS: Specifies the maximum number of days the log files should be kept for. Defaults to 7 days. If both values are specified, MAX_FILE_COUNT takes precedence.

        Attention: To use the age restriction, Powershell must be installed on the Windows system.

      • LOG_DIR: Defines the directory where the log files are located.

      • INTERVAL_MINUTES: Sets the interval at which the cleanup should be performed. Defaults to 60 minutes.

      • LOG_PATTERNS: Defines the log file patterns the script looks for. Specify multiple patterns separated by spaces (e.g. stderr stdout).

    2. Make sure that all necessary services are started

      If you adjust values in the configuration file pe_log_cleanup_conf.bat in the folder <inubit-installdir>\server\process_engine\bin\, then you must restart the LogCleanupService service.

Impacts:

  • Application - Process Engine

Update Virtimo Cluster Manager

This version updates the Virtimo Cluster Manager (version: 2.0). The new Cluster Manager works technically on the JGroups library.

The old and new Cluster Manager versions are therefore not compatible.

Before executing the patch, you must ensure that no unwanted problems occur.

This guide will help you to evaluate the scenarios that may arise and plan suitable solution strategies.

Requirements

You are already using the Virtimo Cluster Manager with INUBIT.

Configuration of the new Virtimo Cluster Manager

Proceed as follows

  1. Running the patch installer creates the following directory: <inubit-installdir>/inubit/server/ibis_root/conf/clustermanager.

  2. Start the patched INUBIT node.

During Process Engine startup virtimo_cluster_manager.xml configuration file will be created automatically from an existing clusterManagerConfig.xml. As soon as the INUBIT node is started, the new cluster manager has an active leader node.

Cluster behavior after applying the patch

By default, cluster nodes are individually removed from a running cluster, patched and then added back to the cluster. The node first logs off from the cluster and then logs back in to the cluster after patching.

By applying this patch, the patched nodes form a new cluster and do not log back in to the previous cluster.

Possible problems

Two separate clusters are created that do not interact with each other and have no knowledge of each other (split brain). Both clusters select a leader node that carries out exclusive work, e.g. runs the scheduler. If there are 2 clusters at the scheduled time of the scheduler, the corresponding workflows are also carried out by both clusters. This can lead to technical errors.

Solution scenarios without downtime

A complete shutdown of the entire cluster is not operationally feasible.

At least one cluster node must be available at all times. No exclusive workflows are carried out during the patching period.

+ Proceed as follows

  • Save the previous configuration

  • Shut down a node of the cluster

  • Patch the node with the patch installer

  • Configure the new cluster node

  • Start up the patched nodes again. If there are problems, stop the node that has just been started up.

  • Repeat the process for all cluster nodes

    A second cluster is formed. Since no exclusive work is being carried out, technical errors are not to be expected.

    1. Exclusive workflows are being carried out during the patching period.

      Proceed as follows

  • Manually intervene in the workflows and prevent the exclusive work from being carried out, e.g. deactivating the scheduler

  • Shut down a node of the cluster

  • Patch the node using the patch installer

  • Configure the new cluster manager

  • Start up the patched nodes again.

    If there are problems, stop the node that has just been started up.

  • Repeat the process for all cluster nodes

    A second cluster is formed. Since no exclusive work is being carried out, technical errors are not to be expected.

Solution scenario with downtime

A complete shutdown of the entire cluster is operationally feasible.

Proceed as follows

  • Shut down the entire cluster

  • Back up the previous configuration

  • Patch all nodes using the patch installer

  • Configure the new cluster manager

  • Start up the patched nodes again.

If you encounter problems, stop the node that has just been started up.

Impacts:

8.1.5

Only standard patch steps are required.

8.1.6

Update X12 metadata file in repository

Action

In the "X12-ENVELOPER.xml" file included in the delivery scope, the maximum length value of the "GS05" (time description) field has been corrected from 4 to 8. To get these changes into the repository, the respective repository directory must be updated manually.

All files in the Global > EDI Specification > Rule Metadata directory are updated. Each updated file is stored in the repository with a new version.

If you have already made changes to files in the repository directory Global > EDI Specification > Rule Metadata or have used a customized version, you can restore your latest version from the corresponding version history.

Requirements

Patch installation has been executed.

Proceed as follows

  • Navigate to the tab "Repository"

  • Right click on the directory "Global > EDI Specification > Rule Metadata"

  • From the context menu Select the option "Update directory"

Impacts:

8.1.7

Only standard patch steps are required.

8.1.8

Aggregated E-Mail support

This patch step is mandatory and must be done before starting the Process Engine.

Requirements

For the newly introduced feature of aggregated error report a new database table is required which must be added to the currently used logsDBConfig.xml file in the Process Engine.

The change must be applied

Process as follows

  1. Stop the Process Engine (if not already done)

  2. Open the file logsDBConfig.xml

  3. Add the following section depending on your database used below the <tables> element:

    • MySQL

    • Oracle

    • Postgres

    • DB2

    • H2

    • MariaDB

    • MSSQL

    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData(is_id BIGINT NOT NULL
            AUTO_INCREMENT,is_server VARCHAR(256),is_serverId VARCHAR(256),is_dateTime
            BIGINT,is_workflowName VARCHAR(256),is_moduleName VARCHAR(256),is_IsErrorKey
            VARCHAR(256),is_IsErrorString VARCHAR(1024),is_errorMailContent
            VARCHAR(1024),is_processId VARCHAR(255),PRIMARY KEY(is_id))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData(is_id NUMBER GENERATED BY DEFAULT AS
            IDENTITY PRIMARY KEY,is_server VARCHAR2(50),is_serverId VARCHAR2(255),is_dateTime
            NUMBER(19),is_workflowName VARCHAR2(255),is_moduleName VARCHAR2(255),is_IsErrorKey
            VARCHAR2(255),is_IsErrorString VARCHAR2(1024),is_errorMailContent
            VARCHAR2(1024),is_processId VARCHAR2(255))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData (is_id SERIAL PRIMARY KEY, is_server
            varchar(50), is_serverId varchar(255), is_dateTime BIGINT, is_workflowName varchar(255),
            is_moduleName varchar(255), is_IsErrorKey varchar(255), is_IsErrorString
            varchar(1024),is_errorMailContent varchar(1024),is_processId varchar(255))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData (is_id BIGINT NOT NULL GENERATED ALWAYS AS
            IDENTITY (START WITH 1 INCREMENT BY 1), is_server VARCHAR(256), is_serverId
            VARCHAR(256), is_dateTime BIGINT, is_workflowName VARCHAR(256), is_moduleName
            VARCHAR(256), is_IsErrorKey VARCHAR(256), is_IsErrorString
            VARCHAR(1024),is_errorMailContent VARCHAR(1024),is_processId VARCHAR(255), PRIMARY KEY
            (is_id))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData (is_id BIGINT AUTO_INCREMENT PRIMARY KEY,
            is_server VARCHAR(256), is_serverId VARCHAR(256), is_dateTime BIGINT, is_workflowName
            VARCHAR(256), is_moduleName VARCHAR(256), is_IsErrorKey VARCHAR(256), is_IsErrorString
            VARCHAR(1024),is_errorMailContent VARCHAR(1024),is_processId VARCHAR(255))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData (is_id BIGINT NOT NULL AUTO_INCREMENT,
            is_server VARCHAR(256), is_serverId VARCHAR(256), is_dateTime BIGINT, is_workflowName
            VARCHAR(256), is_moduleName VARCHAR(256), is_IsErrorKey VARCHAR(256), is_IsErrorString
            VARCHAR(1024),is_errorMailContent VARCHAR(1024),is_processId VARCHAR(255), PRIMARY KEY
            (is_id))
        </createTable>
    </statements>
</workFlowErrorData>
    <workFlowErrorData tableName="inubitWorkflowErrorData">
    <statements>
        <createTable>CREATE TABLE inubitWorkflowErrorData (is_id BIGINT NOT NULL IDENTITY(1,1),
            is_server VARCHAR(256), is_serverId VARCHAR(256), is_dateTime BIGINT, is_workflowName
            VARCHAR(256), is_moduleName VARCHAR(256), is_IsErrorKey VARCHAR(256), is_IsErrorString
            VARCHAR(1024),is_errorMailContent VARCHAR(1024),is_processId VARCHAR(255), PRIMARY KEY
            (is_id))
        </createTable>
    </statements>
</workFlowErrorData>

  4. Save the changes in the logsDBConfig.xml file.

  5. Start the Process Engine

Impacts:

Changed behavior when using generic conversion

Problem

With INUBIT 8.0.45 and 8.1.8, the behavior of the JSON adapter changes. By default, domain conversion is now performed instead of generic conversion. This causes execution to fail on modules where only the module property "json.domain.Type" is set.

The original behavior is restored starting with INUBIT 8.0.46 and 8.1.11.

Workaround

Edit the module and publish it with type "Generic" again.

Impacts:

8.1.9

Only standard patch steps are required.

8.1.10

Only standard patch steps are required.

8.1.11

Only standard patch steps are required.

8.1.12

Only standard patch steps are required.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen