Release Notes

10.5

Back Next

Legacy Audit Trail Migration (Upgrading from a Release Prior to Product 360 10.1)

This section is not applicable if you are using the new Audit Trail introduced with the release of version 10.1 already.

Legacy Audit Trail Database Migration Preparation

We have provided MSSQL and Oracle database scripts for the legacy audit trail database/schema to speed up the migration by removing unnecessary indexes and creating new optimized indexes. Scripts are available in the configuration folder of the audit trail migration:

\server\configuration\HPM\audittrail\migration\dbPreparationScripts

The corresponding script has to be executed on the legacy audit trail database/schema before migration can be started. Please note that this can take a few hours, depending on the database size.

Repository Configuration

Ensure that the repository has all needed Audit Trail configurations in place. This is important because only data for Audit Trail enabled root entities will be migrated, and all other data will be skipped. The entities in the 10.1 and 10.5 repository enabled for Audit Trail do not exactly match those in previous versions. Please check all settings and adapt them to your needs.

In addition to the root entity Audit Trail settings, the "Supports Audit Trail" setting for repository fields will be checked. Only Audit Trail enabled fields and logical keys will be migrated.

audittrail.migration.server.properties configuration

Access to the legacy Audit Trail database should be configured in

<PIM_SERVER_INSTALLATION_ROOT>\configuration\HPM\audittrail\migration\audittrail.migration.server.properties

. This file can be created from a corresponding template. The essential settings here are the host and schema configuration. You can take the settings from the old configuration for Audit Trail.

audittrail.migration.server.properties

### General Host
dest.host                       = host
  
### Default database settings
db.default.type                 = MSSQL
  
...
  
### AuditTrail database/schema
db.audittrail.schema            = HPM_AUDITTRAIL
db.audittrail.schema.backup     = ${db.audittrail.schema}_BAK
db.audittrail.server            = ${dest.host}
db.audittrail.port              = 1433
db.audittrail.user              = user
db.audittrail.password          = password

plugin_customization.ini configuration

In order to use the migration, you have to configure the time period for which you want to migrate changes in the

<PIM_SERVER_INSTALLATION_ROOT>\configuration\HPM\plugin_customization.ini

# ---------------------------------------------------------------------------
# Audit Trail migration preferences
# ---------------------------------------------------------------------------
#
# Audit trail migration starts from today or from the specified 'migrationFromDate' and runs back
# to the specified 'migrationToDate' into the past.
#
#
# 'migrationToDate' 'migrationFromDate' now
# e.g. 2020-01-01 e.g. 2021-04-02
# | | |
# ----------+-------------------------------------------------------+-------------+------> time
#

# Initial start date of the migration means that all old audit trail entries between 'migrationToDate' and
# this 'migrationFromDate' will be transformed to the new audit trail format and stored in elastic.
# This value is optional.
# Date is included.
# Format: yyyy-MM-dd
# com.heiler.ppm.audittrail.migration.server/migrationFromDate =

# All old audit trail entries between today or a defined 'migrationFromDate' and this specified 'migrationToDate' will be transformed
# to the new audit trail format and stored in elastic.
# This value is mandatory.
# Date is included.
# Format: yyyy-MM-dd
# com.heiler.ppm.audittrail.migration.server/migrationToDate =

# Locale to be used for the Audit Trail migration job.
# This should be the same value as it was for the "audittrail.atcsbuilder.locale" property
# in the audittrail.properties file of older versions.
# Default is en_US.
# com.heiler.ppm.audittrail.migration.server/locale=en_US

# Fetchsize of retrieving migration data from the legacy Audit Trail database.
# This value should be between 1 and the maximum database-specific possible fetchsize
# defined in property 'db.default.rowPrefetchSize' (10000).
# In case of some memory issues during the migration, this value should be decreased.
# com.heiler.ppm.audittrail.migration.server/migration.fetch.size = 10000

# Number of threads for retrieving migration data from the legacy Audit Trail database.
# Usually all CPU threads are used for the migration. In case of working with PIM and migrate from the legacy
# Audit Trail database it is worth to decreased the number of maximum thread to work fluid with PIM.
# This value is optional.
# Minimum value is 1, maximum value is number of CPU cores.
migration.maxThreads =

The

migrationToDate

is the end date of the migration. All changes between the given

migrationToDate

and the given

migrationFromDate

(or today if

migrationFromDate

is not set) are migrated to

Elasticsearch

. The

migrationToDate

value is mandatory. The

migrationFromDate

is optional. When the

migrationFromDate

is not set, then today will be used as

migrationFromDate

The

locale

is needed to resolve labels of the objects to be migrated. When the data was written, the

locale

configured for the attribute

audittrail.atcsbuilder.locale

in the

audittrail.properties

file was used. The same value should be used for the data migration. Audit Trail migration uses all CPU cores by default. If the server should run in parallel to the Audit Trail migration, the number of used CPU cores for the Audit Trail migration should be decreased. This can be done by setting the property

migration.maxThreads

to a value between 1 and the number of CPU cores.

Rights

There is a new action right the user must have in order to execute the migration: "Audit Trail, migration" - "Permission to start audit trail migration job". Other rights are not considered in the migration process.

Start Migration

In order to start the migration, start the Desktop UI and open the Management menu. You will find a new entry at the bottom "Start audit trail migration". If the entry is missing, the user probably does not have the corresponding action right to perform the migration. Only one migration job can run at a time, so if the menu entry is disabled, a job instance might already be running.

You can find the executed server job in the process overview perspective under System processes. The problem log of the job will show the progress as well as possible errors.

The number of migrated changes is logged for every processed day. This includes also the number of errors or skipped changes. A change will be skipped if it could not be migrated, details will also be logged, or if its entity is not configured to support Audit Trail.

After Migration

After the migration, you can revoke the migration right from your users. It is not needed to start the audit trail server and the old audit trail database is not used anymore. If you didn't migrate all data and you are not sure if you might need the data again sometime, think about keeping a backup from the database.