Skip to main content
Version: 19.0

Upgrade from ADONIS 16.0 – 16.7 or 17.0 – 17.4 to ADONIS 19.0

This chapter describes how to upgrade an existing ADONIS installation from 16.0 – 16.7 or 17.0 – 17.4 to 19.0.

The upgrade process differs significantly from previous ADONIS releases. Earlier versions ran the application server on Windows, while the web server supported deployment on multiple platforms. Starting with ADONIS 19.0, both the application server and the web server are deployed as containerized services in a Kubernetes environment.

To simplify the migration process, ADONIS 19.0 provides the management tool aupgrade_product. The tool upgrades an existing database to the new version and automatically performs the required migration tasks, including upgrading the database schema, updating the application library, executing migration scripts and preserving component settings.

The migration process consists of the following high-level steps:

  1. Stop the existing ADONIS services.

  2. Back up deployment-specific configuration files.

  3. Upgrade the database using aupgrade_product.

  4. Deploy ADONIS 19.0 in Kubernetes using the backed-up configuration.

  5. Verify the deployment and remove the old installation.

Prerequisites​

Before upgrading ADONIS to version 19.0, ensure that the following prerequisites are met:

  • You are running ADONIS 16.0 – 16.7 or 17.0 – 17.4.

  • Your database is hosted on a supported version of Microsoft SQL Server or PostgreSQL.

  • You have access to a Linux machine, or Windows Subsystem for Linux (WSL), with Docker Engine installed and network access to the database server and the BOC OCI Registry.

  • You have the required credentials for the database server and valid credentials for the BOC OCI Registry.

  • You have access to a Kubernetes environment and the required administration tools, including kubectl and helm.

  • The target environment meets the Hardware/Software Requirements for ADONIS 19.0.

  • You know the password of the ADONIS user Admin.

Application Library for ADONIS 19.0​

You can get started right away if you are using the default library that comes with ADONIS (the ADONIS BPMS Application Library). Custom metamodel changes made on the Properties page in the ADONIS Administration will not affect the update—these changes will be preserved.

If you are using a customized application library, obtain the corresponding updated version from your ADONIS consultant before starting the upgrade.

info

This migration procedure is intended for system administrators with access to the existing ADONIS installation, the database and the target Kubernetes environment.

caution

Create a complete backup of your database before starting the migration. After the database upgrade has completed successfully, the upgraded database can no longer be used with ADONIS 16.0 – 16.7 or 17.0 – 17.4.

Stop Services​

Stop all running ADONIS services (application server and web server) and ensure that no users remain logged in to ADONIS.

To stop the services (on Windows):

  • Open Services. Press <Windows> + <R> to open the Run box, enter services.msc, and then click OK.

  • Stop the ADONIS application server (service name e.g. "ADONISServer17.0Service") and the Apache Tomcat web server (service name e.g. "Tomcat10").

Backup Deployment-Specific Configuration​

Before upgrading the database, back up the deployment-specific configuration files of your existing ADONIS installation.

Earlier versions of ADONIS stored deployment-specific settings in various configuration files. In ADONIS 19.0, these settings are no longer maintained in local configuration files. Instead, they are provided as configuration values during deployment.

The backed-up configuration files will therefore be required later when configuring the new ADONIS 19.0 deployment.

ADONIS Application Server Configuration​

  • <ADONIS 16.x/17.x application server>/conf/server.conf (contains the database name, and application server or aworker processes ports).

  • <ADONIS 16.x/17.x application server>/conf/adoxx.conf (optional, if parameters have been changed from their default value)

  • <ADONIS 16.x/17.x application server>/conf/log.conf (optional, if parameters have been changed from their default value)

Apache Tomcat Configuration​
  • <Tomcat>/webapps/ADONIS16|7_x/adoxx_web.properties (contains the application server IP address and definition of aworker processes)
info

Do not modify the backed-up files. They will be used as a reference when transferring deployment-specific settings to the ADONIS 19.0 deployment.

Upgrade the Database​

To keep using your existing database with ADONIS 19.0, you need to upgrade it using the management tool aupgrade_product. The tool is executed in a short-lived Docker container using the ADONIS application server image.

During the upgrade, aupgrade_product automatically performs all required migration tasks. These include upgrading the database schema, updating the application library, executing the required migration scripts and preserving component settings.

Before executing the upgrade, prepare the working directory, prepare the application library and create the required configuration files as described in the following sections.

Prepare the Working Directory​

Create a working directory on the Linux machine or WSL environment from which you will execute the database upgrade. This directory will contain the configuration files required for the upgrade as well as the generated log files.

The following example creates the working directory /opt/data/config and a directory for the generated log files:

mkdir -p /opt/data/config
mkdir -p /opt/data/logs
note

The examples throughout this guide assume that the working directory is located at /opt/data/config and that the log files are stored in /opt/data/logs. You may choose different locations if required.

Prepare the Application Library​

The database upgrade requires an application library for ADONIS 19.0. During the upgrade, aupgrade_product updates the application library using the specified library file.

Using the Default Library​

If you are using the default library (= the ADONIS BPMS Application Library), no further action is required. The library file is already included in the ADONIS application server image and is located at /aserver/data/default.axl.

Using a Customized Library​

If you are using a customized library, copy the library file you received from your ADONIS consultant into the directory /opt/data/config created in the previous section.

note

The examples in this guide assume that a customized library file is located in /opt/data/config.

Create config.json​

The file config.json controls the upgrade operations performed by aupgrade_product. It specifies whether the database schema is upgraded, whether component settings are preserved and which application library is imported into the upgraded database.

Create the file config.json in the directory /opt/data/config with the following content:

{
  "skipDbScripts": false,
  "beforePreprocessingScripts": [],
  "preprocessingScripts": [],
  "metamodelScripts": [],
  "migrateCompSettings": true,
  "applicationLibrary": "<library-file-name>",
  "additionalComponentSettings": [],
  "postprocessingScripts": []
}

The most important configuration parameters are:

  • skipDbScripts: Leave this value set to false to upgrade the database schema.

  • migrateCompSettings: Leave this value set to true to automatically export the component settings before the upgrade and re-import them afterwards, ensuring that your adaptations to library-specific features are preserved.

  • applicationLibrary: Specify the application library to be used for the database upgrade. If you are using the default library (= the ADONIS BPMS Application Library), specify /aserver/data/default.axl. If you are using a customized library, specify its file name in the directory /opt/data/config, for example custom.axl.

note

Unless instructed otherwise by your ADONIS consultant, leave all remaining configuration parameters unchanged.

Create aupgrade.env​

The file aupgrade.env provides the environment variables required by aupgrade_product. These variables specify the source version, the database connection, the credentials required for the upgrade and the location of the upgrade configuration.

Create the file aupgrade.env in the directory /opt/data/config with the following content and adapt the values according to your environment:

```
SOURCEVER=<16.x|17.x>
HOST=<database-server>
DBNAME=<database-name>
DBTYPE=<SQLServer|PostgreSQL>
DBPORT=<database-port>
DBADMIN=<database-admin-name>
DBADMINPW=<database-admin-password>
ADMINPW=<Admin-password>
PARENTPROJCONFFOLDER=/opt/data
```

The required environment variables are:

  • SOURCEVER: Specify the complete version of your existing ADONIS installation, including the major and minor version.

  • HOST: The host name of your database server.

  • DBNAME: The name of the database to be upgraded.

  • DBTYPE: The type of your database management system. Supported values are PostgreSQL and SQLServer.

  • DBPORT: For default installations, you do not have to explicitly specify the database port. ADONIS automatically uses the standard port 5432 for PostgreSQL or 1433 for SQL Server default instances. Specify this variable only if your database server uses a custom port or a SQL Server named instance.

  • DBADMIN: The user name of a database administrator with sufficient privileges to upgrade the database schema.

  • DBADMINPW: The password of the specified database administrator.

  • ADMINPW: The password of the ADONIS user Admin.

  • PARENTPROJCONFFOLDER: The parent directory of the config directory containing config.json. In the examples throughout this guide, this value is /opt/data.

Log in to the BOC OCI Container Registry​

To log in to the BOC OCI container registry, you will need the access informations and credentials you received from your ADONIS consultant. Login to the BOC OCI registry is required to access the image for the temporary container used to upgrade the database.

The easiest way to log in is to use the standard docker command docker login <boc-registry>. This will prompt you for an access id ("user name") and an access token ("password").

caution

This command stores the credentials in the docker config file in clear text (default: ~/.docker/config.json). If you are currently deploying ADONIS, you can use this file when you log in to the BOC OCI registry with Helm and creating the ImagePullSecret but make sure to safely delete this file afterwards.

note

Do not pass credentials directly as command parameters, the bash command history stores a list of recent commands and could therefore inadvertently reveal the credentials.

Execute the Database Upgrade​

After preparing the working directory, the application library and the required configuration files, execute the following command from the Linux machine or WSL environment to start the database upgrade.

docker run -it --rm \
  --entrypoint "" \
  --env-file aupgrade.env \
  -v /opt/data/logs:/aserver/logs \
  -v /opt/data/config:/aserver/config \
  <boc-registry> \
  sh -c '/aserver/aupgrade_product \
    --srcProductVersion "$SOURCEVER" \
    --id "$DBNAME" \
    --dbInstance "$HOST" \
    --dbType "$DBTYPE" \
    --dbPort "$DBPORT" \
    --dbUser "$DBADMIN" \
    --dbPassword "$DBADMINPW" \
    --adminpw "$ADMINPW" \
    --configRootPath "$PARENTPROJCONFFOLDER"'

The command starts a short-lived Docker container using the ADONIS application server image. The container executes aupgrade_product, performs the database upgrade and terminates automatically after the operation has completed.

info

For Microsoft SQL Server, aupgrade_product uses encrypted database connections by default, matching the default behavior of Microsoft ODBC Driver 18 for SQL Server. If your SQL Server is not configured for encrypted connections, specify --encrypt "optional". If your SQL Server uses an encrypted connection with an untrusted server certificate, you may also need to specify --trustservercertificate "yes". PostgreSQL does not require these parameters.

If the upgrade fails with an SSL or certificate validation error, review the SQL Server encryption settings and adjust these parameters accordingly.

note

ADONIS 19.0 no longer supports Windows Authentication for Microsoft SQL Server databases. Use SQL Server Authentication instead.

The most important parts of the command are:

  • --env-file aupgrade.env: Reads the environment variables from the file aupgrade.env.

  • -v /opt/data/logs:/aserver/logs: Stores the log files generated during the upgrade in the directory /opt/data/logs on the host system.

  • -v /opt/data/config:/aserver/config: Makes the upgrade configuration, including config.json and, if applicable, a customized application library, available to aupgrade_product inside the container.

During the upgrade, aupgrade_product performs the following operations:

  1. Upgrades the database schema.

  2. Exports the existing component settings.

  3. Updates the application library.

  4. Executes the required migration scripts.

  5. Re-imports the component settings.

info

After the database upgrade has completed successfully, the upgraded database can no longer be used with ADONIS 16.0 – 16.7 or 17.0 – 17.4.

Deploy ADONIS 19.0​

After successfully upgrading the database, deploy ADONIS 19.0 in your Kubernetes environment.

note

Deploy ADONIS 19.0 by following the instructions in Deployment of ADONIS.

During the deployment, recreate the deployment-specific configuration of your previous installation using the backed-up configuration values from Backup Deployment-Specific Configuration.

note

The chapter Map Deployment-Specific Configuration to Environment Variables explains how the configuration parameters used by previous ADONIS versions map to the environment variables used by ADONIS 19.0.

Remove the Previous Installation​

After you have successfully deployed ADONIS 19.0 and verified that your users can work with the migrated database, you can remove the previous ADONIS installation.

  • Uninstall the ADONIS 16.0 – 16.7 or 17.0 – 17.4 application server from the Windows server. You can do this through the control panel.

  • Remove the ADONIS 16.0 – 16.7 or 17.0 – 17.4 web application from Apache Tomcat.