9 EMM Updates and Upgrades
With EMM we make a difference between updates (changing to a new minor release, like from 20.10.000.050 to 20.10.000.100) and upgrades (changing to a new major release, like from 20.04 to 20.10).
If you plan to do an upgrade, we strongly recommend to update to the latest minor release of your EMM version, first. Only after that, execute the upgrade to the next major version. This makes sure, that the delta between the two major versions is as little as possible and the old version is well prepared for the upgrade.
If you apply an upgrade to your production environment, make sure to create a backup with EST → Database Maintenance → Backup MariaDB database before, because each upgrade also updates schema and content of your database. You may need the database backup in case of a roll back (see section Rollbacks for EMM below for details). To backup an Oracle database, please use your regular Oracle backup tools.
If you need the files of an EMM version or if you do not want to carry out an update or upgrade by yourself, please contact the AGNITAS support team at support@agnitas.com.
9.1 General Update Process
Before you upgrade EMM to a new major version, check the required software stack in section Software Stack first. If you have to update a component of the software stack like Java, Python or MariaDB, make sure to stop all EMM services on the server before (see chapter EMM Start/Stop for details) to avoid any disruption or misbehaviour of EMM after the update of the software component.
For EMM updates (bug, performance and security fixes) as well as EMM upgrades (new and extended functionality) we offer you to download the individual tarballs for all services and servers of your instance either manually or via EST. The tarballs may also include updates for the EMM database, the EMM runtime environment and the EMM online documentation.
Usually an upgrade consists of a collection of tarballs, while an update may consist of only one or two tarballs. Updates have only the number at the end of the release identifier changed (the hotfix level) and it is ok to mix different hotfix levels on one server.
If you upgrade a EMM version prior to 24.10, do not skip an upgrade of a major version. You have to install and start the GUI service of the frontend tarball of any intermediate version at least once. This ensures that possible migration tasks included in the intermediate EMM version are executed, so that the database and configuration of EMM remains in a consistent state.
Update/upgrade EMM at a convenient time: Do not run an update/upgrade during a dispatch of a mailing, or right after the dispatch (due to downtime of the redirect service causing missed openings and click redirects).
9.1.1 Automated Updates
If you want to update EMM with tool EST (which is the recommended way opposed to the manual update), you may use its interactive mode or its batch mode.
To use EST’s interactive mode, simply launch EST and use menu Install or update package from AGNITAS Website if the current server has Internet access. If not, use menu Install or update package from local file and enter the local path to the update tarball file(s), which you must have downloaded before. EST is able to identify the available EMM services on the current server and offers you interactively to update any backend and frontend service for which an update is available.
If you want to update EMM in batch mode without any user interaction, start EST with parameter -update like
In this case EST updates all EMM services on the current server to the latest available version. This is the easiest way to update a server running EMM services.But if you want to update just a certain EMM service, use
or instead. Replace <URL> with the download link of the specific EMM tarball, respectively replace <file> with the path and file of your local EMM tarball file.9.1.2 Manual Updates
Alternatively, if you want to update EMM manually without the help of EST, the process consists of the following steps:
Step 1:
Copy all provided tarballs to the appropriate servers and release directories (see section Default Directory Structure above). Note: An update can consist of a single runtime tarball only, but not every update or upgrade provides new runtime tarballs.
Step 2:
Unpack all backend tarballs as user root to create the new subdirectories containing the new release of the backend services:
Note: Updates sometimes do not include backend tarballs.
Step 3:
Unpack all frontend tarballs as user root to create the new subdirectories containing the new release of the frontend services:
Note: Updates sometimes do not include frontend tarballs.
Step 4:
Unpack the tarball named backend-runtime-<release>.tar.gz which contains a new version of EST, optionally a new version of the startup script agnitas.sh and has to be unpacked in the root directory of each server:
To activate the new startup script, move the old script to a backup destination and create a symlink to the destination of the original script:
Step 5:
Stop all EMM services on the server with
Step 6:
Delete the old symbolic links referring to the old subdirectories containing the old code.
Step 7:
Create new symbolic links as replacement to connect the new subdirectories with the new release.
Step 8:
Backup your database to have a consistent copy in case of a version rollback.
Step 9:
Update your database to the new version. The new version provides new tables, fields and triggers as well as essential data like new user rights and GUI messages for new features. If you skipped no EMM upgrade (otherwise please contact the AGNITAS support team), you can do the database update ...
… for your MariaDB database by executing shell script emm-mariadb-execute-missing-updates.sh on the server running the GUI service in directory /home/console/webapps/emm/WEB-INF/sql/mariadb. The script checks the current version of your database and applies all SQL update files in the required sequence in one go including emm-messages.sql, userrights.sql and emm-mariadb-migration.sql (see Database Content (MariaDB) for more details). You may either set parameters hostname, username and password directly in the shell script to your individual values, or you will be prompted to enter the values after the start of the script. If you start this script with option dbcfg, the database parameters will be read automatically from /opt/agnitas.com/etc/dbcfg.
… for your Oracle database by executing shell script emm-oracle-execute-missing-updates.sh on the server running the GUI service in directory /home/console/webapps/emm/WEB-INF/sql/oracle. The script checks the current version of your database and applies all SQL update files in the required sequence in one go including emm-messages.sql, userrights.sql and emm-oracle-migration.sql (see Database Content (Oracle) for more details). You may either set parameters hostname, username and password directly in the shell script to your individual values, or you will be prompted to enter the values after the start of the script. If you start this script with option dbcfg, the database parameters will be read automatically from /opt/agnitas.com/etc/dbcfg.
Step 10:
Unpack any runtime tarballs (runtime environment) in case they are provided (see section Runtime Configuration).
Step 11:
Unpack the manual tarball (online help & user manual) in case it is provided (see section Documentation Deployment).
Step 12:
Restart the EMM services on the server with
9.2 General Update and Upgrade Advice
A few things you should keep in mind when updating/upgrading EMM:
- Usually you run more than one service on a server, so you have to update/upgrade each service on the server. For instance a frontend server runs the GUI service, the statistics service and optionally the webservices, while a redirect server runs a frontend redirect service, a backend redirect service and a mailer service.
- Important for upgrades: Do not mix versions, i.e. start using EMM only after you have upgraded all services to avoid problems due to incompatibilities between different versions of services (especially frontend services).
- For manual updates, unpack the tarballs as user root and do not forget option "p" for the tar command to make sure that all files are created with the correct permissions.
- When the upgrade is finished and EMM has been restarted, log into the GUI service of EMM and check the status of the automated background processes in tab Job list of sub-menu System status in menu Administration.
9.3 Manual Update Example for Frontend Services
Since the process for updating and upgrading is identical, we will uniformly use the term "update" in this section.
To make the update steps more clear, here is a detailed example of how to update the GUI service, including an update of the runtime environment, an update of the user manual and an update of the redirect backend service required for the EMM server:
Step 1: Copy update tarballs to their destinations
cp frontend-emm-15.04.328-hf49.tar.gz /home/console/release/emm/
cp backend-rdir-15.04.328-hf49.tar.gz /home/console/release/backend
cp frontend-runtime-<version>.tar.gz /home/console/release/runtime/
Step 2: Unpack update tarball for GUI service
Step 3: Stop GUI service
Step 4: Change symlink for GUI service
Step 5: Backup EMM database with the tool of your choice
Step 6: Update MariaDB database
Step 6: Update Oracle databaseStep 7: Update runtime environment (optional)
Step 8: Update online help & user manual (optional)
cd /home/console/release/manual
tar -xvzpf EMM_Manual_2015.05.15.tar.gz
rm en
ln -s /home/console/webapps/manual/ EMM_Manual_2015.05.15/en en
rm de
ln -s /home/console/webapps/manual/ EMM_Manual_2015.05.15/de de
Step 9: Unpack update tarball for backend services
Step 10: Change symlink for backend services
Step 11: Start GUI service
9.4 Manual Update Example for Backend Services
Below you can find a step-by-step example for the update/upgrade of the merger service.
Step 1: Copy the tarball to its destination
Step 2: Unpack tarball for merger service
Step 3: Stop merger service
Step 4: Change symlink for merger service
Step 5: Start merger service
9.5 Do not Skip Major Versions when Upgrading
When updating EMM, do not skip a major release, i.e. if you use EMM Inhouse 20.10 and you plan to upgrade to EMM Inhouse 21.10, do not skip the upgrade to version 21.04! You have to insert an upgrade to the intermediate major version in order to make sure that no migration processes for the EMM database are missing.
To make sure that you are able to upgrade to each major release of EMM, update to the runtime version of the next major relase and after that download and update the EMM GUI service packages. Do not update the runtime package to a new major release without updating the EMM GUI service package, too!
You only have to install and start the GUI service of the intermediate version (like 21.04 in the above-mentioned case) once. This makes sure that the startup process in the frontend code is executed and initiates all pending migration tasks contained in the skipped EMM version.
For example, the startup process of EMM Inhouse 20.04 migrates all configuration properties from configuration file emm.properties into the database (among other things). This migration is important, because EMM Inhouse 20.10 reads its configuration properties from the database.
9.6 Special advice for Upgrades to Version 23.04
Please note that EMM 23.04 does no longer support MySQL 5.7. See section Migrating from MySQL to MariaDB for the process to migrate from MySQL to MariaDB. If you want to migrate to Oracle DBMS instead, see section Migrating from MySQL to Oracle DBMS for migration instructions.
The EMM database schema for workflows has changed several years ago. With EMM 23.10 we will remove the code to support the legacy format. To check if you are affected, beginning with EMM 23.04, EST will check your workflows at startup time. If EST detects an inactive legacy workflow, you will see message
“Your EMM database contains inactive legacy workflows [list of workflow names]. Please delete those workflows since they will no longer work with EMM 23.10 and later.”
If EST detects an active legacy workflow, you will see message
“Your EMM database contains active legacy workflows [list of workflow names] which can not be migrated. Please rebuild these workflows from scratch and delete the legacy workflows since they will no longer work with EMM 23.10 and later. If you need help, please contact support.”
Please re-build those workflows before you upgrade EMM to version 23.10 or later.
If you want to check manually, if you have legacy workflows in your database, check in table workflow_reaction_tbl if it contains entries with field is_legacy_mode set to value 1.
Also, the report icon will no longer be supported in workflows beginning with EMM 23.10. Therefore, EST will check all workflows for this icon, too. If a workflow is found, you should remove the report icon before you update to EMM 23.10.
9.7 Special Advice for Upgrades to Version 23.10
Starting with version 23.10, you need a license file and a signature file matching your EMM version, which individually unlock the licensed functionality for your instance. You can download these files as a ZIP file via your license link. If you do not know this link, please contact the AGNITAS support team at support@agnitas.com. The license link is also listed in each license file starting with version 23.10.
Install the license file and signature file by copying the ZIP file to the EMM server running the GUI service. Then start EST and deploy the files via menu 4 Security, sub-menu 2 Install license file. Alternatively, you can copy the two files from the ZIP file directly to /home/console/webapps/emm/WEB-INF/classes. In both cases, a restart of EMM on this server is required.
EMM 23.10 needs an update of Python lib paramiko and three new Python libs. Execute
python3 -m pip install -U 'paramiko>=3.2.0'
python3 -m pip install aiosmtplib
python3 -m pip install asyncinotify
python3 -m pip install asyncssh
Once you have finished the upgrade to EMM 23.10, you can remove the requirement of root access for the mailloop service. To do this, stop Postfix on the server running the mailloop service as user root with
and stop the mailloop service as user mailloop with Now, change line in configuration file main.cf in directory /etc/postfix to and restart the mailloop service as user mailloop with Finally restart Postfix as user root with Please note that EMM 23.10 does no longer use deprecated wkhtmltox by default, but NPM package puppeteer to render thumbnail images and PDF documents. Therefore, the installation of nodejs (version 18 or later) and a one-time execution of npm is necessary. See section Rendering of Thumbnail Images and PDF Documents for details.9.8 Special Advice for Upgrades to Version 24.04 and 24.10
If you do not use EMT to update EMM, you have to install some NPM packages manually. On the server running the GUI service, switch to user console, change to directory /home/console/webapps/emm/WEB-INF and install the required NPM packages via port 443 (HTTPS) from the NPM server (operated by GitHub/Microsoft):
This means, that the server running the EMM GUI needs access to the Internet during deployment. If your server does not permit outbound access via port 443, please contact the AGNITAS support team at support@agnitas.com and we will provide you with the node package files which are required at runtime for directories /home/console/.cache/puppeteer/ and /home/console/webapps/emm/WEB-INF/node_modules/.Please make sure to switch to Java 17 as soon as possible, because Java 11 will be no longer supported by EMM 25.04.
Also, we recommend to switch to Python 3.11 as soon as possible, because Python version 3.11 will be a minimum requirement of EMM 25.04.
9.9 Special Advice for Upgrades to Version 25.04
EMT (EMM Maintenance Tool) was renamed to EST (EMM Support Tool).
EMM 25.04 requires Java 17 and Python 3.11 or later. Please make sure to have both versions available on your EMM servers.
MariaDB has to be at least at version 10.6.10 to work with Python 3.11. We use MariaDB version 10.11.7 for our production environment.
EMM 25.04 does not support deprecated wkhtmltox any longer, but uses NPM package puppeteer to render thumbnail images and PDF documents.
After the upgrade, you must delete file derby-10.14.<patch>.jar in directory /home/console/tomcat/lib of the server running the GUI service (<patch> is the placeholder for the exact version).
Please make sure that you import the new licence file via EST → menu 4 Security → submenu 2 Install licence file before starting the new EMM version. You will receive your license file via your individual licence download link. If you do not have the link, please contact our support team at support@agnitas.de.
We recommend to switch from Node.js 18 to version 20:
RHEL:
SLES: If you use Tomcat version 10.1.42 or later, you may have problems to import multiple files and see error message "FileCountLimitExceededException" in log file catalina.out of Tomcat. To avoid this problem, set parameters maxParameterCount and maxPartCount of the Connector configuration in configuration file server.xml to value 1024 each.When you are finished with the EMM upgrade, log into the GUI as user emm-master and check in menu Administration, sub-menu System Status in tab Show Jobqueue that all jobs are working.
9.10 Special Advice for Upgrades to Version 25.11
If you use Tomcat version 10.1.42 or later, you may have problems to import multiple files and see error message "FileCountLimitExceededException" in log file catalina.out of Tomcat. To avoid this problem, set parameters maxParameterCount and maxPartCount of the Connector configuration in configuration file server.xml to value 1024 each.
Please make sure to switch to Java 21 as soon as possible, because Java 17 will no longer be supported by future versions of EMM.
Import your new licence file via EST → menu 4 Security → submenu 2 Install licence file before starting the new EMM version. You will receive your license file via your individual licence download link. If you do not have the link, please contact our support team at support@agnitas.com.
When you are finished with the EMM upgrade, log into the GUI as user emm-master and check in menu Administration, sub-menu System Status in tab Show Jobqueue that all jobs are working.
9.11 Special Advice for Upgrades to Version 26.05
The version 26.05 of EMM requires Java 21 and Tomcat 11. You can update both versions via EST -> menu 2 Configuration -> sub-menu 1 Configure basic environment (Java, Tomcat, Proxy).
Furthermore, we recommend to switch from Node.js 20 to version 22.
RHEL:
Please note that this update of Node.js may update the version of your openssl library too. Now, the new openssl version may not work with your version of openssh any longer and lock you out of your server if you have only remote access via ssh! Therefore, we strongly recommend to run right after the update of Node.js!SLES:
Please note that this update of Node.js may update the version of your openssl library too. Now, the new openssl version may not work with your version of openssh any longer and lock you out of your server if you have only remote access via ssh! Therefore, we strongly recommend to run right after the update of Node.js!To make sure that Tomcat supports the latest TLS crypto algorithms, we recommend to change parameter protocols in Tomcat's configuration file server.xml to
and to add the following line right after "ciphers=..." See section HTTPS for Tomcat for a complete example.AGNITAS uses version 11.4.9 of DBMS MariaDB now. We recommend to use only LTS versions of MariaDB to reduce the need to update MariaDB.
Import your new licence file via EST → menu 4 Security → submenu 2 Install licence file before starting the new EMM version. You will receive your license file via your individual licence download link. If you do not have the link, please contact our support team at support@agnitas.com.
When you are finished with the EMM upgrade, log into the GUI as user emm-master and check in menu Administration, sub-menu System Status in tab Show Jobqueue that all jobs are working.
9.12 Rollbacks for EMM
If you are not happy with a version you updated or upgraded to, you can roll back EMM to a former version or roll forward to a later version with menu Switch EMM version of EST. This menu lists the active versions of the EMM services available on the current server so that you can switch separately
- the runtime environment (including EST itsself)
- the frontend (depending on the installed services this could be GUI service, statistics service, webservices service and redirect service)
- the backend (consisting of the backend utlities neded by a frontend server)
- the manual (including all context sensitive help pages) After you have selected a specific component you get a list of all versions available on the server so that you can chose the version you want to activate.
Warning: If you switch back the frontend or backend not to an older minor version (last 3 digits of the version number), but to an older major version (like going back from 26.05 to 25.11), be advised that the database can not be rolled back. This is, because the upgrade may have deleted or overwritten existing data in your EMM database and this data can not be restored out of thin air. Therefore, you must restore your database backup (see section EMM Updates and Upgrades) first.
If you need to know which services and versions of EMM were active at what time in the past, menu Show update history of EST provides a list of all available services, their versions and the exact startup times.
Do not forget to restart EMM with menu Restart EMM after you have switched the frontend or backend version of EMM.
9.13 Preparations before Updating MariaDB
If you plan to update your version of MariaDB, due to a bug in older versions of MariaDB (MDEV-19292), you may get an error "rowsize too large" afterwards which prevents you from using your EMM database after the update of MariaDB.
Statement from MariaDB regarding this problem:
"Prior to MariaDB 10.2.26, MariaDB 10.3.17, and MariaDB 10.4.7, MariaDB doesn't properly calculate the row sizes while executing DDL. In these versions, unsafe tables can be created, even if InnoDB strict mode is enabled."
To check if you are affected by this bug, please execute SQL statement
SELECT count(*) FROM information_schema.innodb_sys_tables WHERE name LIKE 'emm/%' AND ROW_FORMAT = 'Compact';
ALTER TABLE <table name> ROW_FORMAT = DYNAMIC;
before upgrading your version of MariaDB (after you made a backup of your database, of course)!
To simplify this task for you, EST offers an automated conversion in menu Database Maintenance, sub-menu Check MariaDB table format. Alternatively, here is a little script that does the conversion of all tables (please execute as database user root):
DELIMITER $$
BeginDECLARE done INT DEFAULT FALSE; DECLARE dbtable varchar(100);
declare tab_curse cursor for select SUBSTRING(name, 5) from information_schema.innodb_sys_tables where name like 'emm/%' and ROW_FORMAT = 'Compact';
DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = TRUE;
open tab_curse;
read_loop: LOOP
fetch tab_curse into dbtable;
IF done THEN LEAVE read_loop; END IF;
SET @SQLText = CONCAT('alter table ', dbtable, ' ROW_FORMAT=DYNAMIC');
PREPARE stmt FROM @SQLText; EXECUTE stmt; DEALLOCATE PREPARE stmt;
end loop;
close tab_curse;
END$$
DELIMITER ;
call tmp_convert_row ();
9.14 Upgrading MariaDB
MariaDB recommends these steps to upgrade a MariaDB version:
- Modify the repository configuration, so the system's package manager installs the required version.
- Stop MariaDB.
- Uninstall the old version of MariaDB.
- Install the new version of MariaDB.
- Make any desired changes to configuration options in option files, such as my.cnf. This includes removing any options that are no longer supported.
- Start MariaDB.
- Run mariadb-upgrade.