Upgrading notes for v.2026.5.2 in RPM

This document describes the step-by-step procedure for upgrading OpenIAM when it is installed under the root (/) directory. The steps include disk space validation, environment configuration, database checks, and execution of the upgrade script.

Prerequisites

• OpenIAM is installed under /usr/local/openiam.
• Root or sudo access to the server.
• Database access is established (MySQL / PostgreSQL / MSSQL).
• Target upgrade version is confirmed.
• A backup of the OpenIAM application and database is completed.
• A support case is opened with OpenIAM.

Disk space verification

If OpenIAM is installed under the root (/) directory, verify disk space usage for the OpenIAM path:

du -sh /usr/local/openiam

Recommendation: If /usr/local/openiam is consuming 20 GB, ensure at least 25 GB of free space is available in the / filesystem before proceeding with the upgrade.

Provisioning of the new 'batchtasks' database

Before upgrading, create a new batchtasks database/schema on your existing database server (MySQL/MariaDB, MSSQL, Oracle, or PostgreSQL). The batch task manager applies its own Flyway migrations on first start.

New configuration properties

Configure the following properties (and matching Vault secrets) in datasource.properties.

jdbc.batchtasks.url=<jdbc URL for the new batchtasks DB>
vault.secret.batchtasks.jdbc.username=<username>
vault.secret.batchtasks.jdbc.password=<password>
batchtasks.databaseSchema.name=batchtasks

Deploy the new microservice — migration runs automatically

Deploy the batch-task-manager Helm chart alongside openiam-esb. The ArgoCD application openiam-batch-task-manager is included in the conf repo and points at helmcharts/batch-task-manager.

On the first start of the new service:

1. Flyway applies the batchtasks schema (BATCH_CONFIG, BATCH_SCHEDULE).
2. Existing openiam.BATCH_CONFIG rows are copied into batchtasks.BATCH_CONFIG via JPA (so listeners, audit, and cache see the inserts the same way as any other save).
3. The migration runner short-circuits if batchtasks.BATCH_CONFIG already has rows, so subsequent starts and restarts are no-ops.

BATCH_SCHEDULE is intentionally NOT migrated — the scheduler rebuilds future runs from each task's cron expression, and historical schedule rows have no operational value after cutover.

Notes for developers maintaining custom Groovy scripts

Classes that customer Groovy scripts extend or import were moved out of org.openiam.esb.core.batch.tasks.* as part of the extraction. Any customer-customized Groovy scripts that reference the old packages will fail to compile until imports are updated.

Package moves to apply in customer Groovy scripts:

• org.openiam.esb.core.batch.tasks.implementation.AbstractActivateProcess → org.openiam.batch.manager.initializer.implementation.AbstractActivateProcess
• org.openiam.esb.core.batch.tasks.implementation.AbstractLeaverProcess → org.openiam.batch.manager.initializer.implementation.AbstractLeaverProcess
• org.openiam.esb.core.batch.tasks.AccessCertificationHelper (base class for CustomCertificationHelper) → org.openiam.batch.manager.initializer.AccessCertificationHelper
• org.openiam.esb.core.batch.tasks.TerminatedUsersReportHelper → org.openiam.common.batch.TerminatedUsersReportHelper
• org.openiam.esb.domain.BatchTaskEntity → org.openiam.batch.manager.domain.BatchTaskEntity

More broadly, the entire org.openiam.esb.core.batch.tasks.* namespace has moved to org.openiam.batch.manager.initializer.*. The batch task entity/repository/service/scheduler/MQ-listener packages have moved from org.openiam.esb.* to org.openiam.batch.manager.* (domain, repository, service, scheduler, mq, thread, annotation).

Out-of-the-box scripts shipped in conf/iamscripts/batch/ and conf/iamscripts/bpm/certification/ have already been updated to the new packages.

Upgrade process

1. Update the target upgrade version.
   Edit the OpenIAM environment configuration file:

vi /usr/local/openiam/env.conf

Update the target upgrade version:

export UPGRADE_TO_VERSION="2026.5.2"

2. Configure database parameters (external database only).
   If OpenIAM is using an external database, update the following parameters in env.conf.

export FLYWAY_OPENIAM_HOST=
export FLYWAY_OPENIAM_PORT=
export FLYWAY_ACTIVITI_HOST=
export FLYWAY_ACTIVITI_PORT=
export FLYWAY_GROOVY_HOST=
export FLYWAY_GROOVY_PORT=
export FLYWAY_DATABASE_TYPE="" # possible values: mysql, postgres, mssql

Set the database type explicitly:

DATABASE_TYPE=mysql | postgres | mssql

Execute the upgrade script

Navigate to the OpenIAM utilities directory:

cd /usr/local/openiam/utils

Then run the upgrade script:

openiam-cli upgrade
./upgrade.sh

Non-internet-based upgrade (offline upgrade)

For environments without internet access, update the upgrade script by commenting out the download commands.

Comment out the following lines in the upgrade script:

downloadfile backend.tar.gz https://download.openiam.com/${OPENIAM_ENV}/${OIAM_TYPE}/${UPGRADE_TO_VERSION}/binaries/backend.tar.gz
downloadfile frontend.tar.gz https://download.openiam.com/${OPENIAM_ENV}/${OIAM_TYPE}/${UPGRADE_TO_VERSION}/binaries/frontend.tar.gz
echo "Downloading openiam-$UPGRADE_TO_VERSION.noarch.x86_64.rpm"
curl https://download.openiam.com/${OPENIAM_ENV}/enterprise/$UPGRADE_TO_VERSION/rpm/openiam-$UPGRADE_TO_VERSION.noarch.x86_64.rpm --output /usr/src/openiam-$UPGRADE_TO_VERSION.noarch.x86_64.rpm

Manual file preparation

1. Download the following files manually:

   • backend.tar.gz
   • frontend.tar.gz
   • openiam-<version>.noarch.x86_64.rpm

2. Place the files in the correct directories:

   • backend.tar.gz and frontend.tar.gz → /usr/local/openiam/utils/
   • RPM file → /usr/src/

3. Remove older files from these directories if they already exist.

Support case requirement

Before starting the upgrade:

• Open a support case with OpenIAM.
• The OpenIAM support team will provide the latest and correct download links for the required binaries and RPM files via the support ticket.

Post-upgrade validation (recommended)

Verify that OpenIAM services are running:

✅ Validate application login
✅ Check database schema version
✅ Review logs for errors