Manual Migration

This chapter assumes that the DirX Audit 9.0 upgrade installation has successfully started. If you are upgrading from DirX Audit 7.1 or 7.1 SP1 or 7.1 SP2 or 7.2, the Installation Wizard displays the dialog “Manual Migration Steps” with information that you are upgrading from an older 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 at the DirX support portal) for a more detailed description of changes and updates, including more items than just the list of migration scripts.

When migrating from DirX Audit 7.1, you can continue with the section “Migrating Databases from DirX Audit 7.1 to 7.1 SP1”. When migrating from DirX Audit 7.1 SP1, you can continue with the section “Migrating Databases from DirX Audit 7.1 SP1 to 7.1 SP2”. 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”.

Migrating Databases from DirX Audit 7.1 to 7.1 SP1

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

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

  • 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_71_71SP1.sql

    For Oracle Database:
    No action is required.

  • Migrate 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_71_71SP1.sql

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

Continue with the steps described in the section “Migrating Databases from DirX Audit 7.1 SP1 to 7.1 SP2”.

Migrating Databases from DirX Audit 7.1 SP1 to 7.1 SP2

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

DirX Audit 7.1 SP2 can function with the history entries database from the previous version, but some database objects must be altered.

  • Migrate 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_71SP1_71SP2.sql

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

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

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

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

Checking Apache Tomcat

To run DirX Audit Manager, you must install Apache Tomcat, which serves as the DirX Audit Manager’s and DirX Audit Manager Classic’s container, if it is not already installed. For the supported version numbers, see the DirX Audit Release Notes. Alternatively, you can stop the running Apache Tomcat service and then 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 used specific fact population customization you need to customize the fact and dimension configuration files, it is possible to do that 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 will implicitly use the core default configuration. If core custom configuration folder shared by all tenants is available, its configuration will be merged, same applies for 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 manually edited them.

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 configuration for the connection pool (in sections [database.data.connection_pool.c3p0], [database.config.connection_pool.c3p0] and [database.history.connection_pool.c3p0]) you must introduce the similar values into the new HikariCP sections named [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.

Starting Services

At this point, you have DirX Audit 9.0 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 DirX Audit Manager Classic

Update Report Definitions

If you have custom report definitions, 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 Scheduled Report Jobs

Remove all Generate dashboard chart reports in your existing report sets referring to the following legacy Dashboard components:

  • Risk users based on compound factor by month and risk level

  • Risk users based on simple factor by month and risk level

  • DirX Identity total history certification campaign entries by month and lifecycle state

This step must be performed by all users that have these scheduled report jobs.

Update all report configurations for modified report templates. Several report templates have been updated. If they are included in a scheduled report job, this may require a manual configuration review - this means opening each individual report in a report set and resaving its configuration.

Update Set of Dashboard Components

There are 2 new dashboard components for Audit Manager Classic in DirX Audit 9.0 compared to DirX Audit 7.2 - DirX Identity created and deleted user attribute values by month and User creation succeeded audit events by datetime and operation. These 2 components have to be manually imported if you want to use them.

Remove the following private and public legacy Dashboard components for DirX Audit Manager Classic:

  • Risk users based on compound factor by month and risk level

  • Risk users based on simple factor by month and risk level

  • DirX Identity total history certification campaign entries by month and lifecycle state

and remove all custom components based on the same templates or based on these fact tables:

  • FCT_RSK_COMPOUND_USERS

  • FCT_RSK_USERS

  • FCT_HST_CERTCAMPAIGNS_LIFECYCLE

in the Manage Components list. These components cannot be used anymore. This step must be performed by all users that have these Dashboard components in their lists.