Migrating DirX Audit

Starting the Update / Upgrade Installation

The upgrade or update installation process is performed by the installer and includes updating product components, database schema (if applicable), and configuration settings while retaining existing data and system configuration.

Before starting the upgrade or update installation, perform the preparation steps described in the “Preparing the Migration” section of this document.

Start the upgrade or update installation by running the DirX Audit 9.1.1 installer. For details about installation, see the chapter “Installing DirX Audit” in the DirX Audit Installation Guide.

Performing the Manual Migration Steps

This chapter assumes that the DirX Audit 9.1.1 upgrade or update installation has successfully started. If you are upgrading or updating from DirX Audit 7.1 SP2, 7.2, 9.0, or 9.1, the Installation Wizard displays the dialog “Manual Migration Steps” with information that you are upgrading from an older version or updating on the same version and must execute the manual steps described in this chapter.

At this stage, perform all the relevant steps described in this chapter to update your environment to the new DirX Audit version.

We also suggest consulting the DirX Audit Migration Guide (this guide) for each respective version (available in the DirX Support Portal) for a more detailed description of changes and updates, including items beyond the migration scripts listed here.

When migrating from DirX Audit 7.1 SP2, you can continue with the section “Migrating Databases from DirX Audit 7.1 SP2 to 7.2”. When migrating from DirX Audit 7.2, you can continue with the section “Migrating Databases from DirX Audit 7.2 to 9.0”. When migrating from DirX Audit 9.0, you can continue with the section “Migrating Databases from DirX Audit 9.0 to 9.1”. When migrating from DirX Audit 9.1, you can continue with the section “Migrating Databases from DirX Audit 9.1 to 9.1.1”.

Migrating Databases from DirX Audit 7.1 SP2 to 7.2

Migrating the databases to DirX Audit 7.2 consists of migrating the audit messages database schema (Data DB) and the history entries database schema (History DB) for each tenant.

DirX Audit 7.2 can function with the same audit messages and history entries databases from the previous version, but some database objects must be altered. The migration must be done in several phases.

  • Migrate the audit messages database schema - run the following SQL script in your audit messages database (Data DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_data_71SP2_72.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_data_71SP2_72.sql

  • Begin the migration of the history entries database schema - run the following SQL script in your history entries database (History DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_history_71SP2_72_part1.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_history_71SP2_72_part1.sql

  • Clean up the DirX Identity domain and optionally the history entries database - remove duplicate LDAP entries with the dxthistdbtool command line tool and its ldapremdup command by following the steps described in the section "Remove Duplicate LDAP Entries" in the DirX Audit Command Line Interface Guide. You may want to synchronize the changes made in the DirX Identity domain to the DirX Audit History Database. In this case, the following extension to the existing SQL Server JDBC connection string in the tenant configuration (install_path/conf/tenants/tenantID/configuration.cfg) could be required if you do not use a secure connection to your SQL database: encrypt=false.

    Example:

    dxthistdbtool ldapremdup
     -ldapconfig ldap.properties
     -tenantid 6bc24196-327d-441c-8d66-3633ee6b887b
     -synctohistdb

  • Clean up the history entries database - ensure there are unique history entries in the DirX Audit History Database with unique and non-missing dirxEntryUUID values with the dxthistdbtool command line tool and its makeunique command by following the steps described in the section “Make History Entries Unique” in the DirX Audit Command Line Interface Guide.

    Example:

    dxthistdbtool makeunique
     -ldapconfig ldap.properties
     -tenantid 6bc24196-327d-441c-8d66-3633ee6b887b
     -csvfile duplicates.csv

  • Finish the migration of the history entries database schema - run the following SQL script in your history entries database (History DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_history_71SP2_72_part2.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_history_71SP2_72_part2.sql

Continue with the steps described in the section “Migrating Databases from DirX Audit 7.2 to 9.0”.

Migrating Databases from DirX Audit 7.2 to 9.0

Migrating the databases to DirX Audit 9.0 consists of migrating the configuration database schema (Config DB), the audit messages database schema (Data DB) and the history entries database schema (History DB) for each tenant.

DirX Audit 9.0 can function with the same configuration, audit messages and history entries databases from the previous version, but some database objects must be altered.

  • Migrate the configuration database schema - run the following SQL scripts in your configuration database (Config DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_config_72_90.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_config_72_90.sql

  • Migrate the audit messages database schema - run the following SQL scripts in your audit messages database (Data DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_data_72_90_ddl_0.sql
    install_media/Additions/Scripts/MSSQL/migrate_data_72_90_dml_0.sql
    install_media/Additions/Scripts/MSSQL/create_data_procedures.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_data_72_90_ddl_0.sql
    install_media/Additions/Scripts/Oracle/migrate_data_72_90_dml_0.sql
    install_media/Additions/Scripts/Oracle/create_data_procedures.sql

  • Migrate the history entries database schema - run the following SQL scripts in your history entries database (History DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_history_72_90_ddl_0.sql
    install_media/Additions/Scripts/MSSQL/migrate_history_72_90_dml_0.sql
    install_media/Additions/Scripts/MSSQL/migrate_history_72_90_ddl_1.sql
    install_media/Additions/Scripts/MSSQL/create_history_procedures.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_history_72_90_ddl_0.sql
    install_media/Additions/Scripts/Oracle/migrate_history_72_90_dml_0.sql
    install_media/Additions/Scripts/Oracle/migrate_history_72_90_ddl_1.sql
    install_media/Additions/Scripts/Oracle/create_history_procedures.sql

Continue with the steps described in the section “Migrating Databases from DirX Audit 9.0 to 9.1”.

Migrating Databases from DirX Audit 9.0 to 9.1

There are no required migration steps when migrating the databases from DirX Audit 9.0 to DirX Audit 9.1.

DirX Audit 9.1 can function with the same configuration, audit messages and history entries databases from the previous version, but some database objects must be altered or recreated.

The new Audit Manager (introduced in DirX Audit 9.0) uses a new configuration database schema. The old configuration data that have been created with previous versions (such as scheduled report jobs, dashboards and stored filters) will not be migrated automatically. You will either need to create these configuration objects from scratch in DirX Audit Manager after the migration or request help for manual migration of stored old configuration data from DirX Audit Manager Classic to DirX Audit Manager by contacting DirX Support.

You can delete the old configuration data from the configuration database schema after you have created the new configuration objects in DirX Audit Manager, but it’s not necessary for the migration.

Running the drop scripts for the old configuration database (Config DB) mentioned below will permanently delete certain configuration objects, such as scheduled report jobs in DirX Audit Manager Classic. These configuration objects will not be migrated automatically to DirX Audit Manager. You will either need to create these configuration objects from scratch in DirX Audit Manager after the migration or request help for manual migration of stored old configuration data from DirX Audit Manager Classic to DirX Audit Manager by contacting DirX Support. You don’t have to drop the old configuration database schema. Those database objects are not used by DirX Audit 9.1 and will not affect the functionality of DirX Audit 9.1. You can keep the old configuration database schema for reference purposes.

It’s recommended to back up the configuration database (Config DB) using standard DB tools before running the drop scripts.

  • (Optional step) Drop the old configuration database schema - run the following SQL scripts in your configuration database (Config DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/drop_config_pre_91.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/drop_config_pre_91.sql

Continue with the steps described in the section “Migrating Databases from DirX Audit 9.1 to 9.1.1”.

Migrating Databases from DirX Audit 9.1 to 9.1.1

Migrating the databases to DirX Audit 9.1.1 consists of migrating the history entries database schema (History DB) for each tenant.

DirX Audit 9.1.1 can function with the same configuration, audit messages and history entries databases from the previous version, but some database objects must be altered.

  • Migrate the history entries database schema - run the following SQL scripts in your history entries database (History DB) server console.

    For SQL Server:
    install_media/Additions/Scripts/MSSQL/migrate_history_9.1.0_9.1.1.sql
    install_media/Additions/Scripts/MSSQL/create_history_procedures.sql

    For Oracle Database:
    install_media/Additions/Scripts/Oracle/migrate_history_9.1.0_9.1.1.sql

Next, continue with the steps described in the following sections.

Checking Apache Tomcat

To run DirX Audit Manager, you must install Apache Tomcat if it is not already installed. Apache Tomcat hosts DirX Audit Manager Classic in versions 7.1 SP2, 7.2, and 9.0, and hosts DirX Audit Manager in versions 9.0, 9.1, and 9.1.1. DirX Audit Manager Classic is not deployed in versions 9.1 and 9.1.1. For supported version numbers, see the DirX Audit Release Notes. If Apache Tomcat is already installed and was used before the upgrade, stop the running Apache Tomcat service and remove the folder tomcat_install_path/work/Catalina/localhost/AuditManager.

Clearing Cached Internet Browser Data

We recommend that you remove the cached web content data, cookies and site data from your internet browser. This step is mandatory for Firefox, where you can find it in browser Settings → Privacy & Security → Cookies and Site Data → Clear Data.

Migrating Fact Population Configuration Files

If you use fact population customizations, you need to customize the fact and dimension configuration files. You can do this for all tenants or for a specific tenant.

Copy the common core default configuration from the folder:

  • install_path/conf/defaults/fact-configuration

into the core custom configuration folder shared by all tenants in:

  • install_path/conf/fact-configuration

and/or into the tenant custom configuration folder in:

  • install_path/conf/tenants/tenantID/fact-configuration
    where tenantID is a unique tenant identifier.

Now you can customize configuration files for all and/or specific tenants.

Components that create or update fact tables, facts, and dimensions implicitly use the core default configuration. If the core custom configuration folder shared by all tenants is available, its configuration is merged. The same applies to the tenant custom configuration folder.

Perform your customization. See the section "Customizing Fact and Dimension Tables" in the "DirX Audit Customization Guide" for details on the process of customizing these files.

Migrating Tenant Configuration Files

The JDBC connection pool library was changed from C3P0 to HikariCP in DirX Audit version 9.0.

You need to migrate the connection pool configuration if you edited it manually.

You need to edit the following file for each tenant:

  • install_path/conf/tenants/tenantID/configuration.cfg

You need to remove the following keys if they exist in the file (only the line with connection_pool.impl key):

[database.data]
connection_pool.impl = c3p0
[database.config]
connection_pool.impl = c3p0
[database.history]
connection_pool.impl = c3p0

If you have any customized connection pool configuration (in sections [database.data.connection_pool.c3p0], [database.config.connection_pool.c3p0], and [database.history.connection_pool.c3p0]), you must introduce equivalent values into the new HikariCP sections [database.data.connection_pool.hikaricp], [database.config.connection_pool.hikaricp], and [database.history.connection_pool.hikaricp].
The keys are different for each connection pool implementation. See the keys in the default tenant configuration file install_path/conf/defaults/tenant/configuration.cfg and connection pool implementation documentation.

Performing Initial Configuration

Now you can start the initial Core and Tenant configuration for each of your tenants by clicking Next in the Installation Wizard.

DirX Identity Synchronization Workflows are discontinued in DirX Audit 7.2 and replaced with History Synchronization based on LDAP. The existing workflows are migrated during the initial tenant configuration. For more details, see “Discontinued DirX Identity Synchronization Workflows Migration Connectivity Configuration” in the DirX Audit Installation Guide.

During DirX Audit configuration, an automatic procedure runs and performs migration steps. However, you must also perform some of the migration steps later as separate tasks, as described in the next sections.

For more information about the configuration process, see the section “Configuring DirX Audit” in the DirX Audit Installation Guide.

When the Configuration Wizard completes, finish the installation: Click Done to quit the installer.

Finishing the Update / Upgrade Installation

This section describes the steps that you need to follow after the installation is complete.

Starting Services

At this point, you have DirX Audit 9.1.1 installed and at least one tenant configured on your system. Now start the DirX Audit services, if not already started, in this order:

  1. DirX Audit Message Broker

  2. DirX Audit Server tenant_display_name, a separate instance of DirX Audit Server is created for every tenant

  3. The Apache Tomcat service where you deployed DirX Audit Manager (and where DirX Audit Manager Classic was deployed in older versions such as 7.1 SP2, 7.2, or 9.0)

Update Report Definitions

If you have custom report definitions for DirX Audit Manager Classic, please contact DirX Support to request the conversion of your XML-based data used in DirX Audit Manager Classic into the JSON-based format which is required in DirX Audit Manager.

Update Report Template Files

If you have custom report template files such as compiled (.jasper) and source (.jrxml, .jrtx), it is necessary to migrate them to a newer version.

With the release of JasperReports Library 7, there are breaking changes affecting both compiled (.jasper) and source (.jrxml, .jrtx) report files created with JasperReports Studio version 6 or older. Compiled .jasper files are no longer backward compatible. Source .jrxml templates need to be recompiled with the new version of JasperReports Studio.

Updating files in JasperReports Studio 7:

  • Backup your existing .jrxml and .jrtx files

  • Download and install JasperReports Studio Community Edition version 7.0.3 from https://community.jaspersoft.com/download-jaspersoft/community-edition/

  • Set the compatibility to JasperReports 7.0.0 by selecting Window → Preferences → Jaspersoft Studio → Compatibility

  • Open your existing .jrxml and .jrtx files

  • Make any change in the file and then undo the change; this triggers recompilation of the source file

  • Save the updated files

Update Private Views Used for Report Sets

Open and save all existing private views (Dashboard, Audit Analysis, or History view) that are to be used in Report Sets. This step is required to add properties that were not saved in previous versions.