Migration guide

This guide explains how to migrate Atoti Limits from versions 4.1.1 to 4.2.0. This migration guide focuses on breaking changes. Consult the Atoti Limits 4.2.0 release notes and changelog for a complete view of changes.

What is the recommended migration process?

1. Back up your project.
2. Automatically migrate your code and/or data using the Atoti Limits migration tool.
3. Perform a diff between older Atoti Limits release builds and newer release builds.
   • Update your dependencies.
   • Update your code.
4. Confirm successful build and startup.

How do I use the Atoti Limits migration tool?

The Atoti Limits migration tool is shipped with the Atoti Limits distribution files in the limits-migrations folder. It is a script written in Java that automates part of the migration process by updating your code and/or data to be compatible with the latest version of Atoti Limits.

How does the Atoti Limits migration tool work?

In general, the tool is installed and run as follows:

1. cd limits-migrations
2. Run mvn clean install
3. Run java -jar path/to/limits-migrator-tool-exec.jar <target-version> <other-args>

Replace <target-version> with the version you are migrating to (e.g. 4.2.0), and <other-args> with the version specific arguments accepted by the migration tool for the target version. See the following section for more details.

4.2.0 migration script

This migration script updates the following files from Atoti Limits 4.1.x to 4.2.x:

• limit_structures*.csv: Adds new columns Limit Workflow Variables and Incident Workflow Variables.
• limits_approve*.csv: Renames the LimitValues column to Limit Value. Adds a new column Limit Changes Workflow Variables.
• incident*.csv: Adds a new column Limit Type.

The original files are backed up in a separate folder, which you can delete after completing your migration. All new columns will be initialized as empty. This script expects the following program arguments (in this order):

1. The target version of Atoti Limits, which should be 4.2.0
2. The glob pattern of the structure files to be migrated, for example *.csv or **/*structures*.csv.
3. The glob pattern of the limit files to be migrated, for example *.csv or **/*limits_approve*.csv.
4. The glob pattern of the incident files to be migrated, for example *.csv, **/*incidents*.csv or **/2025-12-09/incidents/*.csv.
5. The root folder of the files, for example ./data or /path/to/data.

What dependencies have changed?

The following dependency changes are required for migrating Atoti Limits 4.1.1 to Atoti Limits 4.2.0.

Updated

Added

Removed

How do I migrate my project?

The following information is applicable for migrating Atoti Limits 4.1.1 to Atoti Limits 4.2.0.

Low-Code/No-Code

If you are using Atoti Limits 4.1.1 in a low code/no-code setup and migrating to Atoti Limits 4.2.0, you’ll need to know high-level changes. This section focuses on the high-level changes when migrating, such as configuration/property, data model, cube, and dashboard changes.

• Loading data
  • Moving from the DLC to the new file loading service
  • Additional fields for the structure csv file/database table
  • Additional field for the limit csv file
  • Additional field for the incidents csv file/database table
• Limit definition changes
  • Warning threshold behavior

Loading data

Moving from the DLC to the new file loading service

In order to migrate your initial load configuration from the DLC to the new file loading service, you need to update the following properties in your application.yml file:

The following properties do not have an equivalent in the new configuration and can be safely removed:

If you previously modified the behavior of the DLC by overriding the default values of these properties, and you wish to maintain the same behavior, you will need to implement a custom ILimitsFileLoadingService as described in How to customize the file loading service.

Additional fields for the structure csv file/database table

The structure files now have additional fields Limit Workflow Variables and Incident Workflow Variables, located in the final two columns. These fields indicate the default variables that can be set when initiating limits and incidents workflows respectively. These fields are used to build the objects that are stored in the Limit Workflow Details field on the structure.

If you are loading data from CSV files, which is the default, you will need to update your structure files to include this new column. A migration script is provided for this, or alternatively you can manually add the column.

If you are loading data from a persistent database, you will need to include the new column limit_workflow_details in your tables. A Liquibase migration changelog is provided for this. See the Limits Data Migration section for more details on how to apply the changelog. Alternatively, you can manually add the column with the following sql command:

ALTER TABLE "limit_structure"
    ADD "limit_workflow_details" VARCHAR(255);

Additional field for the limit csv file

The limit files now have an additional field Limit Changes Workflow Variables located in the final column. This field indicates the variables set when initiating limit workflows. We have also renamed the LimitValues column to Limit Value.

If you are loading data from CSV files, which is the default, you will need to update your limit files to include these changes. A migration script is provided for this, or alternatively you can manually add the column.

In the persistent mode, the value is ultimately stored in the Activiti database, so there is no need here for a database migration script.

Additional field for the incidents csv file/database table

The incident files now have an additional field Limit Type, located in the fourth column, that indicates the type of limit used in the evaluation: OFFICIAL or TEMPORARY.

If you are loading data from CSV files, which is the default, you will need to update your incident files to include this new column. A migration script is provided for this, or alternatively you can manually add the column.

If you are loading data from a persistent database, you will need to include the new column in your tables. A Liquibase migration changelog is provided for this. See the Limits Data Migration section for more details on how to apply the changelog. Alternatively, you can manually add the column with the following sql command:

ALTER TABLE "incident"
    ADD "limit_type" VARCHAR(255);

Limit definition changes

Warning threshold behavior

Starting in version 4.0.1, the interpretation of the warning threshold of a limit was changed from the original behavior to better align with the wording in the UI. The behavior, along with the wording in the UI and Atoti Limits documentation, has since been updated to clarify that the warning threshold is directly correlated to the limit utilization percentage.

If you started using Atoti Limits or updated the warning threshold of your limits in version 4.0.1 or later, you may need to update the warning thresholds to ensure they are still aligned with your expectations.

For example, consider a limit with the following settings:

• Breach when value is: GREATER_THAN
• Warning threshold: 80%
• Absolute value: False
• Limit value: 1000

Prior to version 4.0.1, the limit would warn when the value was between 200 and 1000. From version 4.0.1 to 4.1.x, the limit will warn when the value is between 800 and 1000. From 4.2.0 on, the limit will warn when the value is between 200 and 1000, so the behavior is the same as prior to version 4.0.1.

Up to version 4.1.x the wording in the UI was “Warn when within % of limit value”. The wording has been updated in 4.2.0 to “Warn when utilization reaches % of a limit” to better reflect the behavior.

For more information on the warning thresholds, see the designing limits section.

Code-first

If you are using Atoti Limits 4.1.1 in a code-first setup and migrating to Atoti Limits 4.2.0, you’ll need to know both high-level as well as low-level changes. This section focuses on the low-level API changes when migrating.

• Loading data
  • Moving from the DLC to the new file loading service
  • Date roll via file no longer supported
  • Managing Workflows

Loading data

Moving from the DLC to the new file loading service

The following DLC-related configuration classes have been removed along with their associated imports/beans:

If you have customized the DLC configuration in Atoti Limits by overriding the default implementations of these configuration classes, you will need to replace your custom DLC beans with a custom implementation of the ILimitsFileLoadingService interface. See How to customize the file loading service for more details on how to override the default service.

Once you have created your custom ILimitsFileLoadingService implementation that mirrors the behavior of your previous DLC configuration, you can safely remove all DLC-related configurations from your project.

Date roll via file no longer supported

With the removal of the DLC, rolling the date by sending the updated AsOfDate file to the DLC endpoint is no longer supported. Please use the Limits asOfDate endpoint to roll the date instead.

Managing Workflows

If you have made customizations to the default workflows then you will need to update them to conform to the new workflow service.