Upgrade database driver (and check connection settings)

Details about the database driver and the connection configuration are summarized in the following sections. Before executing the ImageMaster configuration script (configureAppServer.sh) you must adjust the required parameters and copy the driver jar file into the expected directory location.

ImageMaster 9.14.1 database requirements overview

The ImageMaster requirements for databases have changed according to the compatibility guide [T Compatibility Guide]. If an unsupported database or database driver is in use, you must consider an upgrade of the database and related database driver.

If your previously used database driver is still supported with the new release of ImageMaster 9.14.1, you can copy this from your old installation. If you need to upgrade your database or driver, you must obtain new driver files for your specific database, for example, by downloading them from the vendor. A database upgrade in terms of upgrading the database version is not in scope of this documentation. You must refer to the database vendor documentation for this. Only the upgrade of the database driver and the ImageMaster database model (via the ImageMaster 9 Upgrade Tool) is described here.

If you upgrade an MS SQL Server database, consider this:

• If the distributed transaction components were previously installed by using “EXEC sp_sqljdbc_xa_install” like it is foreseen in SQL Server 2017 CU 16 onwards and SQL Server 2019, no further steps are required.

• Otherwise, if in your previous installation “sqljdbc_xa.dll” was installed manually using the DLL provided with the JDBC driver, then the DLL must be upgraded on the SQL server as well [SQL Server XA]. (In practice, this could only be the case if you upgrade from an ImageMaster release before 9.9.2.)

• Concerning TLS encryption:

Since Microsoft JDBC driver version 10.2 (supported in ImageMaster since release 9.12.1) the default driver value for the property “encrypt” changed into “true”. It means that the JDBC connection to the SQL Server uses TLS encryption per default. Therefore, all the following related TLS properties must be taken into account: encrypt, trustServerCertificate, trustStore, trustStorePassword, and hostNameInCertificate.

In case the “trustServerCertificate” property is set to “false” (default value) you have to provide the trust material at connection time either by using the “trustStore” and “trustStorePassword” connection properties explicitly, or by using the underlying Java Virtual Machine (JVM)'s default trust store implicitly.

Depending on the security level, which the JDBC connection shall fulfill, the TLS properties must be set according to the Microsoft documentation.

Example scenarios: There is an option to turn off TLS encryption and override the default value of the “encrypt” property by “false”, which is not recommended for production systems. Rather consider if it would be acceptable from a security perspective to skip the server certificate validation but keep the TLS encryption. In this case the “trustServerCertificate” property in the JDBC connection URL could be set to “true”:

trustServerCertificate=true

Pattern of a JDBC connection URL, where the property must be set:

jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

• Also see:

• “Understanding encryption support” [SQL Server Encryption]

• “Connecting with encryption” [SQL Server Connection]

Steps for driver installation

1. Set the parameter jdbcJarPath in the ImageMaster configuration file (configureAppServer.config).

   The value must contain the path and full filename of the driver jar file.

2. Copy the driver jar file into the above specified path.

Steps for database datasource configuration

Check or adjust the settings ImageMaster configuration file (configureAppServer.config) in the following sections:

• ## Database Commons

• Depending on your database type adjust settings in:

  • ## Database - Oracle

  • ## Database - POSTGRESQL

  • ## Database - SqlServer

• ## Credential Store

  If the credential store is internally created (credentialStoreInternal=true), define the passwords by:

  • imaDbPassword

  • imaAuditDbPassword

  If the credential store is externally created, it is required that it provides this password using the alias:

  • imaDbPasswordAlias

  • imaAuditDbPasswordAlias

Concerning the configuration above, remember that always two datasources are present in an ImageMaster environment even if the audit trail feature is not licensed. Both cases are possible: the datasources can either point to the same database with exactly the same connection and authentication parameters or they can differ.

Oracle driver check example

You can check the exact version of an Oracle driver in the following way:

Rename the database driver jar file to extension ZIP and extract the driver package to a folder. Inside the folder you will usually find the file MANIFEST.MF in the directory META-INF. In the manifest file you will find the details of the database driver version. The example below displays the unsupported version 11.2.0.3 for an Oracle driver:

In the above example the Oracle version is 11.2 patch level 3 (11.2.0.3) that does not match the requirements of ImageMaster.