3.0 Migration Guide

In this document, we will see the major steps to migrate from 2.8 to 3.0.

Please check the change log for detailed list of fixes, changes and improvements introduced in 3.0.

Database migration

Migration scripts are available there.

Cleaning up duplicate documents

In the former versions, the generated documents with Template were stored twice in the database and the file system.

Two scripts are provided to help identify and clean up the duplicates (which were unreachable by the application anyway). This allows you to reclaim the wasted disk space.

Step 1: Identify and delete duplicate records

The SQL script delete-duplicated-documents.sql identifies pseudo-duplicate documents.

To run the script:

psql -d your_database -f delete-duplicated-documents.sql

This script will:

  1. List all duplicate documents found

  2. Delete duplicate records from meta_file, dms_file, and meta_attachment tables

  3. Export the list of duplicate file paths to files_to_delete.txt

This script permanently deletes the duplicated records from the database. Make sure to backup your database before running it.

Step 2: Delete duplicate files from the filesystem

After running the SQL script, use the bash script delete-files.sh to remove the duplicate files from the filesystem.

Usage:

# Dry-run mode (preview what will be deleted)
./delete-files.sh \
  --base-dir /path/to/upload/directory \
  --file-list /files_to_delete.txt \
  --dry-run

# Actual deletion
./delete-files.sh \
  --base-dir /path/to/upload/directory \
  --file-list /files_to_delete.txt

Parameters:

  • --base-dir (required): The base directory where uploaded files are stored

  • --file-list (required): Path to the file containing the list of files to delete

  • --dry-run (optional): Preview mode - shows what would be deleted without actually deleting files

The script will:

  1. Read the file list

  2. Delete each file from the filesystem

  3. Display a summary of deleted files, files not found, and errors

  4. Clean up the file list if all deletions were successful

Breaking Changes

If you have not overridden the code of template module, you can ignore this section.

Upgrade dependencies

Due to AOP upgrade to java 21, the following dependencies have been upgraded:

  • axelor-utils to 4.0.0

  • axelor-message to 4.0.0

  • axelor-studio to 4.0.0

  • axelor-guardian to 3.0

  • axelor-template-library to 3.0.0

  • okhttp to 5.3.0

  • mockito-core to 5.20.0

  • lombok to 1.18.42

  • java-jwt to 4.5.0

  • javax.websocket-api is replaced by jakarta.websocket-client-api 2.2.0

  • AOP to 8.0.0

  • Java to 21

  • Tomcat to 10

  • Gradle to 8.14.3

Enums Relocations

The enums ApiEndpoint and ApiEndpoint have been moved from com.axelor.template.enums to com.axelor.templateapi.enums.

Enums renaming

Old name

New name

OutputFormats

InputFormat

Data Transfer Objects Relocations

DTO Replaced by

AuthResponseDto

com.axelor.templateapi.beans.AuthToken

TemplateConsumptionInformation

com.axelor.templateapi.beans.CustomerCount

TemplateResponseDto

com.axelor.templateapi.beans.GenericApiResponse

Constants Relocations

The following constants have been moved from TemplateExceptionMessage to TemplateApiClientExceptionMessage:

  • UNEXPECTED_DEFAULT_TRUST_MANAGERS

  • FAILED_TO_CREATE_NEW_HTTP_CLIENT

  • NO_UUID_RETRIEVED

  • CANNOT_DELETE_TEMPLATE

  • CANNOT_DELETE_DOCUMENT

  • CANNOT_FETCH_STATUS

Constants Removal

The following constants have been removed from the class TemplateExceptionMessage

  • AUTH_FAILED

  • RESPONSE_BODY_IS_NULL

Methods Relocation

Method From To

findOutputFormats

TemplatePrintModelOutputService

OutputFormatHelper

generateTargetField

ExpressionBuilderService

ExpressionBuilder

addTargetField

ExpressionBuilderService

ExpressionBuilder

The services TemplatePrintModelOutputService and ExpressionBuilderService have been removed

Templates management

The methods managing models on TemplateApiService have been replaced by new methods in com.axelor.templateapi.helper.UploadHelper:

Old method New method

TemplateApiService.uploadTemplate(File)

UploadHelper.upload(TenantApiUser, File)

TemplateApiService.updateTemplate(String, File)

UploadHelper.update(TenantApiUser, String, File)

TemplateApiService.downloadTemplate(String)

UploadHelper.upload(TenantApiUser, String)

TemplateApiService.deleteTemplate(String)

UploadHelper.delete(TenantApiUser, String)

Printing

The methods managing printing on TemplateApiService have been replaced by new methods in com.axelor.templateapi.helper.PrintingHelper:

Old method New method

TemplateApiService.generateDocument(String, Map<String, Object>)

PrintingHelper.generate(TenantApiUser, GenerationPayload, String)

TemplateApiService.downloadDocument(String)

PrintingHelper.download(TenantApiUser, String)

TemplateApiService.deleteDocument(String)

PrintingHelper.delete(TenantApiUser, String)

  • The method PrintRequestService.fetchRequestStatus() has been replaced by PrintingHelper.getStatus(TenantApiUser, String)

Auth services

The class AuthService has been replaced by com.axelor.templateapi.helper.AuthHelper:

Old method New method

AuthService.login()

AuthHelper.login(TenantApiUser)

AuthService.getJwt()

AuthHelper.getJwt(TenantApiUser)

AuthService.logout()

AuthHelper.logout()

Classes relocation

Old class New class

CreateRequestService

com.axelor.templateapi.helper.CreateRequestHelper

ApiService

com.axelor.templateapi.helper.ApiHelper

WebClientHelper

com.axelor.templateapi.helper.WebClientHelper

ExpressionBuilder entity

  • The entity ExpressionBuilder is removed

  • The field field is moved to TemplateSettingsLine

  • The other fields defined within ExpressionBuilder are no longer stored in the database. They are replaced by dummy fields.

Limit exceed removal

To improve the user experience, the notification process for exceeding printing limits has been removed.

Admins can still monitor printing usage and consumption directly from the dashboard.

As a result of this change, the following elements have been removed:

  • The method TemplatePrintController.checkLimit

  • The constant TemplateExceptionMessage.LIMIT_EXCEEDED_ALERT

  • The action action-template-print-method-check-limit