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.
Component

Components involved in the patch step.
Action

Action(s) that must be performed.

8.0.16

Update BPC modules to version 4.0.14

Refer to Update of the INUBIT BPC modules.

Load external references in XML

Prerequisites

It is not mandatory to configure these JVM properties.

By default, external DTD and external entity loading are disabled, DOCTYPE is allowed but not resolved.

The loading of XML is used extensively in INUBIT. This starts with the configuration files, continues with the communication between Workbench and Process Engine, also includes the execution of modules up to the display of watchpoints in a technical workflow.

Proceed as follows

For change those default settings additional JVM properties must be set in the start scripts of Workbench, CLI, Server or Remote Connector. The following properties are allowed:

-DDISABLE_EXTERNAL_DTD

true (default) | false

Deactivate (true) or activate (false) loading of external DTDs

-DDISABLE_DOCTYPE

true | false (default)

Disallow (true) or allow (false) DOCTYPE usage in XML

-DDISABLE_EXTERNAL_ENTITY

true (default) | false

Deactivate (true) or activate (false) resolving of external entities inside XML

Example

To adjust the configuration in the Process Engine startup script, the following file is opened: <inubit-installdir>/inubit/server/process_engine/bin/setenv.sh

And adds the following lines to the JVM_PARAMS block:

JVM_PARAMS="$JVM_PARAMS -DDISABLE_EXTERNAL_DTD=true"
JVM_PARAMS="$JVM_PARAMS -DDISABLE_DOCTYPE=true"
JVM_PARAMS="$JVM_PARAMS -DDISABLE_EXTERNAL_ENTITY=true

8.0.17

Update EDIGAS files in repository

This step is optional and only necessary if you use EDI in connection with EDIGAS messages using auto-detection.

Requirement

The INUBIT Process Engine has started
You are connected to the process engine with a workbench
You have access to the repository

How to proceed

Update the EDIGAS-MESSAGES.xml file in the repository
1. Download the latest version of EDIGAS-MESSAGES.xml online from Virtimo sources or reach out to Virtimo support
2. Switch to the Repository tab
3. Select the following path in the navigation tree: Global > System > EDI Specification > Rule Metadata
4. Switch to the file table
5. Right-click to open the context menu and select the following entry: "Import…"
6. Chose the downloaded file EDIGAS-MESSAGES.xml and finish the import
7. Alternatively, you can also import this directly under Global.
Remove the EDIGAS-SUBSETS.xml file from the repository
1. Switch to the Repository tab
2. Select the following path in the navigation tree: Global > System > EDI Specification > Rule Metadata
3. Right-click on the "EDIGAS-SUBSETS.xml" file in the table on the right
4. Execute the following entry from the context menu: "Delete…"
Remove the EDIGAS-SUBSETS.xml file from the server file system

In addition to deleting from the repository, the file (if any) must also be removed from the INUBIT server file system at <inubit-installdir>/inubit/server/ibis_root/ibis_data/repository/deploy/Global/System/EDI Specification/Rule Metadata to prevent deployment to the repository the next time the Process Engine is started.

Process Engine - Updating JDK to 11.0.18

Action

As the java distribution has been updated automatically to version 11.0.18 during patch installation, check whether manual steps are necessary.

Proceed as follows

Refer to Updating JDK

Update BPC modules to version 4.0.15

Refer to Update of the INUBIT BPC modules.

8.0.18 Spring 2023

Workbench - Update the Widgets directory in the repository

Running the patch updates the files widget.xsl and widget_bpc.xsl in the repository. If you have made any manual adjustments to these files, create a backup before running the patch.

This step is optional and only necessary if one the below folders is not appearing in the Workbench after patching:

Global > System > Widgets > ExtTreePanel
Global > System > Widgets > resources

Tree Widgets is used by BPC INUBIT WebApp module and Process Interaction module.

Prerequisites

Process Engine is up and running.
You are logged-in into a Workbench as a System Administrator.

Proceed as follows

Switch to tab Repository
In the navigation tree choose the following path: Global > System > Widgets.
Open the context menu by right-clicking the folder Widgets in the tree.
Click on the action Update directory.
The directory including its subdirectories will be updated.
The missing folders and their content will be visible afterward.

BPC - Temporary activation to load inline JavaScript in a browser

This step is required if you are using INUBIT WebApp or INUBIT Process Interaction module in BPC.

The above modules use JavaScript, which is located directly in the HTML output. By default, the Karaf instructs browsers not to execute such JavaScript code. In order for the modules to work, this Content-Security-Policy-Header statement in the Karaf must be adapted so that browsers execute such JavaScript code.

Prerequisites

Karaf’s configuration file jetty.xml has been relocated as described here
BPC/Karaf has been stopped

Proceed as follows

Open the file jetty.xml

Locate the section "Set Response Headers"

    <!-- ==================== -->
    <!-- Set Response Headers -->
    <!-- ==================== -->
    <Call name="insertHandler">
        <Arg>
            <New id="RewriteHandler" class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
                <Set name="rules">
                    <Array type="org.eclipse.jetty.rewrite.handler.Rule">
                           ...
                    </Array>
                </Set>
            </New>
        </Arg>
    </Call>

Find the Item element "header-csp".
1. If no such element exists add a new Item element.
To the element <Set name="value"> add behind script-src the value 'unsafe-inline'.

The Item element should look like this:

<Item>
  <New id="header-csp" class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
    <Set name="pattern">/*</Set>
    <Set name="name">Content-Security-Policy</Set>
    <Set name="value">script-src 'self' 'unsafe-eval' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self'; frame-ancestors 'self'; form-action 'self'; worker-src 'self' blob: ;</Set>
  </New>
</Item>

Safe and close the file
Now you can start BPC/Karaf

Process Engine - Updating Tomcat to 9.0.73

Action

As Tomcat has been updated automatically to version 9.0.73 during patch installation, check whether manual steps are necessary.

Proceed as follows

Refer to Updating Tomcat

Update BPC modules to version 4.1.0

Refer to Update of the INUBIT BPC modules.

8.0.19

Remove Elasticsearch

Since Elasticsearch is no longer used from BPC version 4.1.0 and replaced by Opensearch.

Prerequisites

BPC is used together with Opensearch
All data are available in Opensearch

Proceed as follows

Stop the BPC
Run the patch installer and update the BPC installation
1. Opensearch will be installed and configured.
2. For a manual conversion, follow the instruction.
Navigate to the <bpc_install_dir>/bpc folder.
Back up all necessary files and folders in the elasticsearch sub-folder
Remove the elasticsearch subdirectory
Start the BPC

Update BPC modules to version 4.1.1

Refer to Update of the INUBIT BPC modules.

8.0.20

Only standard patch steps are required.

8.0.21

BPC - Temporary activation to load inline JavaScript in a browser

This step is required if you are using INUBIT WebApp or INUBIT Process Interaction module in BPC and encounter problems related to JavaScript code execution.

By default, the Karaf applies CSP restrictions informing browsers to prevent inline JavaScript code execution. In order for the affected modules to work, any JavaScript must be loaded via referencing the resource properly.

As a temporary workaround the inline JavaScript execution can be re-enabled by setting a specific module property.

Enabling inline JavaScript execution is potentially a security risk. Virtimo recommends strongly to rework all JavaScript usage towards using JS files referenced from within the HTML.

Prerequisites

BPC is up and running
BPC user with admin rights is logged in

Proceed as follows

Open the INUBIT WebApp modules configuration tab in BPC
Select the module instance where the inline JavaScript should be re-enabled
In the specific module’s configuration set the property "SanitizeHTML" to value false (deselect checkbox).

Process Engine - Updating JDK to 11.0.19

Action

As the java distribution has been updated automatically to version 11.0.19 during patch installation, check whether manual steps are necessary.

Proceed as follows

Refer to Updating JDK

Update BPC modules to version 4.1.2

Refer to Update of the INUBIT BPC modules.

8.0.22

Checking the API key stored for BPC

Requirements

The INUBIT is linked to the BPC Portal
An API key was stored in the server configuration under Portal > Portal server > BPC

How to proceed

Log in to the Process Engine using the workbench
Go to the Administration > General Settings tab
In the tree structure on the left, select Portal > Portal server
Check the value for the "API Key for the BPC connection" option
If the value is filled, you do not need to do anything else
If the value is empty, continue here
Click on the "…" button on the right in the same table row
In the "API key for the BPC connection" dialog that opens, select an API key from the dropdown or click on the New button
As soon as a new API key is displayed, close the dialog by clicking on the OK button
Click on the Save button in the toolbar → The BPC API key is now set and updated accordingly on the Process Engine

Update BPC modules to version 4.1.3

Refer to Update of the INUBIT BPC modules.

8.0.23

Workbench - Update the IS Configuration directory in the repository

Running the patch installer updates the file configuration.xml under Global> System> Mapping templates > IS Configuration in the repository. If you have made any manual adjustments to the file, create a backup before running the patch.

Prerequisites

Process Engine is up and running.
You are logged-in into a Workbench as a System Administrator.

Proceed as follows

Switch to tab Repository
In the navigation tree choose the following path: Global > System > Mapping Templates> IS Configuration
Open the context menu by right-clicking the folder IS Configuration in the tree
Click on the action Update directory

The directory including its subdirectories and configuration.xml file will be updated and ready to be used.

8.0.24

Update BPC modules to version 4.1.5

Refer to Update of the INUBIT BPC modules.

8.0.25 Winter 2023

Update OAuth2 properties of system diagrams

Prerequisites

The INUBIT Process Engine is started and available

Do the following

Log in as System Administrator with the INUBIT Workbench.
From the burger menu, open Configuration > System Diagrams.
Open the systemdiagram_config.xml file.
Apply all OAuth2 properties from the <inubit-installdir>/inubit/server/ibis_root/conf/systemdiagram_config_template.xml file.
Click the OK button*.
Restart the INUBIT Process Engine

Process Engine - Updating Tomcat to 9.0.80

Action

As Tomcat has been updated automatically to version 9.0.80 during patch installation, check whether manual steps are necessary.

Proceed as follows

Refer to Updating Tomcat

Process Engine - Updating JDK to 17.0.7

Action

As the java distribution has been updated automatically to version 17.0.7 during patch installation, check whether manual steps are necessary.

Proceed as follows

Refer to Updating JDK

Process Engine – Update H2 database

Prerequisites

The H2 database is used as an INUBIT internal database.

The use of the H2 database is not recommended for productive use.

Action

By updating INUBIT to this version, a previously used H2 database file will no longer be accessible. Therefore, the contents of this database must be backed up before patch installation.

Do the following

Stop the Process Engine

Back up the H2 database file with the following command:

java -cp h2-<old-driver-version>.jar org.h2.tools.Script -url jdbc:h2:/<path-to-old-db-file>/<database-name> -user <username> -script backup.zip -options compression zip

The file backup.zip is created, which contains the contents of the H2 database.

Remove the following files:
- <inubit-installdir>/inubit/server/ibis_root/ibis_data/database/<h2-db-file-name>
- If present: <inubit-installdir>/inubit/server/ibis_root/log/dbh2
Run the patch installer

Restore the backed up H2 database content:

java -cp h2-<new-driver-version>.jar org.h2.tools.RunScript -url jdbc:h2:/<path-to-new-db-file>/<database-name> -user <username> -script backup.zip -options compression zip

The database file is restored from the file backup.zip at the specified path.

Using the latest script files

Action

Start the Process Engine

INUBIT is now being rolled out with JDK 17. To do this, various script files in INUBIT had to be adapted. In order to use these changes to the script files, manual adjustments are necessary.

Proceed as follows

Follow the instructions under updating script files.

Update BPC modules to version 4.1.8

Refer to Update of the INUBIT BPC modules.

8.0.26

Only standard patch steps are required.

8.0.27

Only standard patch steps are required.

8.0.28

Process Engine – Prevent disclosure of server information

It is considered a potential security vulnerability to leak server information (server name, version, etc.) in responses sent by a server application. This type of information has already been removed from all server responses, the only exception being the error responses.

Action

Updating the INUBIT with the patch installer also removes the server information from error responses.

The content of the server response is controlled via the <ErrorReportValve> entry in the server.xml file. For more information, see here.

Proceed as follows

Check the server.xml file. It should not contain an ErrorReportValve entry. If so, we recommend checking the file entry manually after running the patch installer.
Run the patch installer. The necessary entry <ErrorReportValve> is added or adjusted in the server.xml file.

Manual check

Open the server.xml file
Find the lines with the entry <ErrorReportValve>
Make sure: showServerInfo="false"

The value false indicates that no server information should be sent in error responses.

Further adjustments to the ErrorReportValve are possible. For more information, see here.

8.0.29

Only standard patch steps are required.

8.0.30

Add IGUASU connector in system diagram and deployment

Action

It is necessary to update the systemdiagram_config.xml file to override the IGUASU Connector module properties in system diagrams.

Process as follows

Go to the burger menu and open the "Configuration" menu
Open the "System diagrams…" entry within the configuration.
Switch the view of the systemdiagram_config.xml file to text format

At the end of the file add the following entry:

<Resource name="IGUASU Connector">
   <Target class="com.inubit.ibis.configuration.workflowtool.systemdiagram.shapes.ExtSystem"/>
   <Properties>
     <Property name="IguasuURL" type="String" displayName="ServerURL"/>
   </Properties>
</Resource>

Save the systemdiagram_config.xml file
Close the dialog

Action

It is necessary to update the ibis_deploy.xml file to override module properties of the IGUASU Connectors in deployment.

Proceed as follows

Go to the burger menu and open the "Configuration" menu
Open the "Deployment…" entry within the configuration.
Switch the view of the ibis_deploy.xml file to text format

At the end of the file add the following entry:

<Property name="IGUASU Connector" type="ListProperty">
   <Property name="IguasuURL" type="String" displayName="ServerURL"/>
   <Property name="IguasuCallableFlowKey" type="String" displayName="FlowID"/>
</Property>

Save the ibis_deploy.xml file
Close the dialog

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

8.0.31

Update BPC modules to version 4.1.9

Refer to Update of the INUBIT BPC modules.

8.0.32

Upgrade Keycloak to version 24.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 24.0. 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

Read Keycloak Migration Guide to learn about the latest migration changes.
Stop the Keycloak server if it is running.
Read Preparing for upgrading and follow the preparation steps.
Run the Virtimo Digitalization Suite patch installer and upgrade to the latest Keycloak version on your computer.
Read Migrating the database and follow the database migration steps.
Read the remaining sections like Migrating themes and follow the instructions.
Once all the above steps are completed, start the Keycloak server.
Login to Keycloak admin console and navigate to Realm Settings and change the value of "Unmanaged attributes" to "Enabled"
Navigate to Authentication and then to Required Actions tab . Change the value of "Verify Profile" to "off"

8.0.33

Only standard patch steps are required.

8.0.34

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.

8.0.35

Update ActiveMQ Client library to version 5.18.4

Prerequisites

You are already using one of the JMS providers, e.g. ActiveMQ.

Action

If you get a runtime error like NoSuchMethodError() when using the JMS provider, make sure that no other versions of the JMS API are present in <inubit-installdir>/inubit/server/process_engine/webapps/ibis/WEB-INF/lib.

Do the following

Stop the Process Engine
Remove the provider-specific JMS JAR file from <inubit-installdir>/inubit/server/process_engine/webapps/ibis/WEB-INF/lib
Start the Process Engine

8.0.36

Plugin JSON Formatter in INUBIT registration

In order to use the INUBIT plugin "JSON Formatter" it needs to be registered so it become available in module editor and workflow designer.

Action

Stop the Process Engine
Rename the plugin.xml.bak into plugin.xml under <inubit‑installdir>/server/ibis_root/conf>.

Add JSON Formatter plugin details to the plugins.xml:

<Plugin>
    <Name>JSON Formatter</Name>
    <PluginGroup>Utilities</PluginGroup>
     <ClientJavaClass>de.virtimo.inubit.plugins.jsonformatter.JSONFormatterClient</ClientJavaClass>
    <ClientComment>JSON Formatter</ClientComment>
    <ServerJavaClass>de.virtimo.inubit.plugins.jsonformatter.JSONFormatter</ServerJavaClass>
    <ServerComment>JSON Formatter</ServerComment>
    <Image>icons/60x40.colored/json_formatter.svg</Image>
    <PluginComment/>
    <LastUpdateUser>root</LastUpdateUser>
    <LastUpdateTime>25.09.2024 10:00:00</LastUpdateTime>
</Plugin>

Rename profile.xml.bak into profile.xml under <inubit‑installdir>/server/ibis_root/conf>.
Add the entry below entry to all the profiles which need this plugin:
```
<Use>JSON Formatter</Use>
```
Save all changes
Start the Process Engine

8.0.37

AS4 log file path

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

Action

Stop the Process Engine
Change the following entry to <inubit-installdir>/inubit/server/ibis_root/log/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
```
Save all changes
Start the Process Engine