Managing timezone migration

Starting in Maximo® Real Estate and Facilities 9.2, manage the timezone migration process to adjust date and time values when the application server timezone changes.

Before you begin

Before you manage timezone migration, help ensure that you meet the following requirements:

You have system administrator privileges with database access to run SQL queries and back up and restore the database.
You have access to the Maximo Real Estate and Facilities Admin Console.
You have access to the Red Hat OpenShift console.
You know the old server timezone value and the new server timezone value.
You have a database backup and standard recovery plan available.
You schedule a planned downtime window for the migration process.

Important: Run timezone migration before any users start by using the application after the timezone change to avoid data corruption.

Note: This tool is intended for system administrators only. It is not intended for regular business users.

About this task

The timezone migration process starts automatically during server startup when the system detects a difference between the previous server timezone and the current server timezone. Before you run the migration, you must set the previous server timezone value in the database.

Procedure

Verify the current server timezone.
Use one of the following commands based on your operating system:
- Linux: timedatectl, date, or cat /etc/timezone
- Windows: tzutil /g (Command Prompt) or Get-TimeZone (PowerShell)
Set the previous server timezone value in the database.
- Use SQL queries:
  1. Check whether a previous server timezone record exists:
```
SELECT VALUE FROM ENVIRONMENT_PROPERTIES 
WHERE ENVIRONMENT='platform.db.property' 
AND PROPERTY='PREVIOUS_SERVER_TIMEZONE'
```
  2. If the query returns no results, insert a new record:
```
INSERT INTO ENVIRONMENT_PROPERTIES (ENVIRONMENT, PROPERTY, VALUE) 
VALUES ('platform.db.property', 'PREVIOUS_SERVER_TIMEZONE', 'timezone_value')
```
  3. If the query returns a result, update the existing record:
```
UPDATE ENVIRONMENT_PROPERTIES
SET VALUE='timezone_value'
WHERE ENVIRONMENT='platform.db.property'
AND PROPERTY='PREVIOUS_SERVER_TIMEZONE'
```
    Note: Use this UPDATE query only when you skipped the migration process at first run or entered an incorrect timezone value.
  Replace timezone_value with the actual timezone value.
Restart the application server pods.

The timezone migration process starts automatically during server startup.
Monitor the migration progress by reviewing the timezoneMigration.log file.
The log file is located in the application server log directory. Look for the following messages:
- Migration initialization
- Identification of affected data
- Processing activity for batches or groups of records
- Warnings or failures
- Completion message
The log4j2.xml configuration file in the config directory manages the log file configuration. Each log file has a maximum size of 500 MB. The system generates up to 10 log files before it starts to overwrite the oldest file.
Monitor system resources during the migration process.
Monitor the following resources:
- Application server health
- CPU and memory usage
- Database performance
- Disk space for logs
Wait for the migration process to complete.

The process is complete when the logs show that a successful completion message and the application starts normally.

After successful migration, the system updates the previous timezone value in the database to match the current timezone value.
Validate business data after completion.

Review sample business records to confirm that date and time values are correct.

Results

The timezone migration process completes successfully, and all non-relative date fields are adjusted to the new timezone.

What to do next

If the migration process fails, review the timezoneMigration.log file for error messages. The system resumes the migration from the failed stage on the next server startup.

How to skip timezone migration

The timezone migration process is skipped automatically when the previous server timezone and the current server timezone are the same, or when no previous server timezone value is specified in the database. Although you can skip the process in production environments, it is not recommended if the timezone changes.

Important: If you skip the process, you must run it later before you create any new records to avoid data corruption.

How to fix an incorrect value inserted for previous server timezone

To fix an incorrect previous server timezone value, use the Admin Console method (recommended):

From the navigation menu, click Admin Console > Timezone Migration.
In the timezone selection field, enter or select the previous server timezone. This value must be the timezone that the server was using before the change.
Click Save.

or the UPDATE SQL query in Step 2. After you update the value, restart the application server pods.

What to do if the process fails in the middle

If the timezone migration process fails, the system logs the failure in the timezoneMigration.log file. Successfully completed work remains completed, and unprocessed work is not treated as completed. The system automatically resumes the migration from the failed stage on the next server startup. Before you allow normal system usage, review the issue in the log file. If the failure persists, contact IBM Support.

How to find a list of affected fields

Use this query to identify all non-relative date fields affected by timezone migration:

SELECT DISTINCT 
    SO.SPEC_TEMPLATE_ID,
    SO.NAME AS BO_NAME,
    SO.SPEC_CLASS_TYPE AS MODULE_ID,
    M.MODULE_NAME,
    OM.TABLE_NAME AS DATA_TABLE,
    SF.ATR_NAME AS FIELD_NAME,
    OM.COLUMN_NAME AS DB_COLUMN_NAME,
    SF.RELATIVE_DATE_TIME
FROM SOBJTYPE_FIELDS SF
JOIN SMART_OBJ_TYPE SO 
    ON SF.SPEC_TEMPLATE_ID = SO.SPEC_TEMPLATE_ID
JOIN OBJECT_FIELD_MAP OM 
    ON SF.SPEC_TEMPLATE_ID = OM.BO_ID 
    AND SF.ATR_SEQ = OM.ATR_SEQ
JOIN IBS_MODULE M 
    ON SO.SPEC_CLASS_TYPE = M.MODULE_ID
WHERE SF.ATR_TYPE IN ('Date')
    AND SF.RELATIVE_DATE_TIME = 0
    AND SF.DELETED_FLAG = 0
    AND OM.TABLE_NAME IS NOT NULL
ORDER BY OM.TABLE_NAME, SF.ATR_NAME

Follow these guidelines to help ensure a successful timezone migration:

Run timezone migration only during planned downtime.
Take a database backup before you start timezone migration.
Review the old and new server timezone values carefully.
Monitor logs throughout the process.
Validate business data after completion.
Help ensure consistent timezone configuration across all nodes in the environment.
Allocate sufficient time for the migration process. The time that is required depends on the number of records that contain non-relative date fields.
Allocate more CPU resources to application server pods to improve migration performance through increased concurrent thread execution.