Migration guide 4.1

This guide explains the changes required to migrate to the stated version of the Atoti Limits.

Migrate to 4.1.1

Upgrading from version 4.1.0, see the Atoti Limits 4.1.1 Release Notes.

Atoti Limits is using Atoti Server 6.1.3 and Atoti UI ~5.2.6.

For new features and fixes included in these releases, please see the Atoti UI documentation and Atoti UI Migration Notes, and the release notes for Atoti Server.

Summary

• Limit warnings: Intrepretation of the warning threshold limit has been updated.

Warning threshold

In version 4.1.0, the interpretation of the warning threshold was updated. The new behavior, along with the
Atoti Limits and Atoti UI documentation, clarifies that the threshold is a direct percentage of the limit’s utilization. If you updated a limit’s warning threshold or defined new warning thresholds using Atoti Limits in version 4.1.0, you may need to update your warning thresholds to ensure they are still aligned with your expectations.

Example

The following illustrates the updated behavior. Consider a limit with these settings:

• Rule: GREATER_THAN
• Warning: True (80%)
• Absolute Value: False
• Limit Value: 1000

The UI wording and warning range have changed as summarized in the following table:

Migrate to 4.1.0

Upgrading from version 4.0.3, see the Atoti Limits 4.1.0 Release Notes.

Atoti Limits is using Atoti Server 6.1.3 and Atoti UI ~5.2.6.

For new features and fixes included in these releases, please see the Atoti UI documentation and Atoti UI Migration Notes, and the release notes for Atoti Server.

Summary

• Authentication: JWT is now the default authentication for machine-to-machine communication. Basic authentication has been removed.
• Removal: limits-activeviam and /limits/rest/v2/limitDefinition/limitsDefinitionStoreQuery have been removed.
• Interface changes: Several interfaces have been updated or removed (IAuthenticatedLimitUserService, IEvaluationService, IValidationError), custom implementations may need updates.
• “Save” operation changes: Atoti Limits now strictly enforces create vs. update logic based on the presence and existence of IDs.
• Temporary limits: sourceLimitId is now validated. Temporary limits are grouped under their official source limits in API responses.
• Security filtering: @PostFilter and @PostAuthorize are now applied in ILimitsRetrievalService to enforce user-based result filtering.
• Auto-configuration: Now uses @ConditionalOnMissingBean to simplify custom bean injection and avoid needing @Primary.

Breaking changes

• Endpoint removal: Removed the /limits/rest/v2/limitDefinition/limitsDefinitionStoreQuery endpoint used when evaluating in favor of using the ILimitCacheService.
• Module removal: The limits-activeviam module has been removed from the released source files.
• Authentication changes: JWT is now the default machine-to-machine (MtM) authentication. This will require property changes in your Atoti Server and Atoti Limits.
• IAuthenticatedLimitUserService changes: With the removal of Basic authentication, some methods in IAuthenticatedLimitUserService are no longer required and have been removed.
• Evaluation service change: There is a new method in IEvaluationService, which you will need to implement if you have a custom implementation of this interface.
• Validation error changes: The IValidationError interface has been modified. If you have any custom validation errors you will need to update them accordingly.

Module removal

The limits-activeviam module has been removed from the released source files. This is to enforce best practices that will ultimately improve the developer experience. Providing a clean separation between source code and custom code makes migrations easier.

We don’t recommend that you modify the source code of limits-activeviam. Instead, use Spring injection to add to or modify the default behavior of the core code. You can find examples of this in the Extending the module section of our documentation.

If you have modified the source code of limits-activeviam, you need to extract your changes into the limits-starter module and use Spring to inject the changes. If you can’t use Spring injection, please raise a Jira ticket in order for us to provide the appropriate hooks.

In the meantime, you can override the limits-activeviam code in limits-starter by adding your code with the same class and package name as in limits-activeviam.

JWT is now the default machine-to-machine (MtM) authentication

Atoti Limits now uses JWT authentication for machine-to-machine communication. This is the default authentication method for Atoti Limits and your Atoti Server. Therefore, you need to set the limits.autoconfiguration.service-principal property on both the Atoti Limits and your Atoti Server to communicate between servers. This service-principal user should have sufficient rights to perform all limit related operations.

You should remove the following unused properties in your Atoti Server:

• limits.autoconfiguration.authentication
• limits.autoconfiguration.content-server.authentication
• limits.autoconfiguration.limits-authentication

IAuthenticatedLimitUserService changes

The following methods were required to support Basic authentication which has been removed in favor of JWT authentication. They have been removed from IAuthenticatedLimitUserService:

• runWithAuthentication
• decodeBase64EncodedAuthentication

If you have a custom implementation of IAuthenticatedLimitUserService that overrides the default interface implementation of these methods, you can safely remove them from your code.

Functional Interface changes

The beans used for MtM authentication have been updated to return only builders and have been renamed. These changes provide more consistency and better flexibility. If you have customized the MtM authentication, you will need to update your code accordingly.

The following interfaces have been updated:

Additional Method in IEvaluationService

An overloaded version of the evaluateLimits method has been added to the IEvaluationService interface that allows you to control whether a notification is sent when the evaluation is complete:

Collection<Incident> evaluateLimits(Collection<LimitEvaluationTask> limitEvaluationTasks, boolean sendNotification);

If you have a custom implementation of IEvaluationService, you will need to add this method to your implementation.

Validation error changes

The structure of validation errors has been streamlined to improve readability and usability. These changes impact the error objects themselves, as well as the error handlers. If you have custom validation errors or error handlers in your project, you’ll need to migrate them accordingly.

IValidationError changes

• new method added: String getFieldName() - returns the name of the field containing the error.
• method getLineNumber() was renamed to getIndex().
• method getColumnIndex() was removed (replaced by getFieldName()).
• method getSource() was removed.

IValidationErrorHandler changes

• The handleValidationFailure and handleValidationError methods no longer take a source argument, since the source isn’t stored on the validation error.

Input file formats

No changes.

Configuration

Configuration properties

Properties added

limits-activeviam module

Properties deleted

Configuration files

Files Modified

application.yml

New properties:

Datastores

No changes.

Databases

No changes.

Cube schema

No changes.

Measures

No changes.

Context values

No changes.

Other changes

@PostFilter and @PostAuthorize in ILimitsRetrievalService

The methods of ILimitsRetrievalService have been updated to use the Spring @PostFilter and @PostAuthorize annotations to filter the results based on the user’s roles. This change is applied at the interface level for all methods, so all implementations of this interface will be affected. For custom internal calls that should not filter the results, you can use the methods that accept a LimitsQueryPayload argument and set checkUserPermissions to false. Please keep in mind that any user-facing invocations of these methods should always have checkUserPermissions set to true to ensure users only see the limits they are authorized to access.

The @PostFilter annotation applies to methods that return java Collections. The @PostAuthorize annotation applies to methods that return a single object.

Behavior change for “save” methods/endpoints

The default behavior of the “save” methods and endpoints in Atoti Limits has changed. Previously, “save” operations attempted to update the existing object if the incoming object had the same ID as an existing object. Otherwise it was treated as creation. If the incoming object did not have an ID or had an ID that did not match an existing object, a new object was created.

Now, the “save” methods and endpoints follow these rules:

• “save” a single object:
  • If the incoming object does not have an ID, it will be treated as a create operation that will fail if an object with that ID already exists.
  • If the incoming object has an ID, it will be treated as an update operation that will fail if no object with that ID exists.
• “save” a collection of objects:
  • If any of the incoming objects are missing an ID, all objects are treated as create operations that will fail if any contain an ID that already exists.
  • If all incoming objects have an ID, all are treated as update operations that will fail if any of the IDs do not exist.

The following methods and endpoints are affected by this change:

• DefaultLimitsAppCrudService.java:
  • saveLimitStructure
  • saveLimitStructures
  • saveLimit
  • saveLimits
  • saveIncident
  • saveIncidents
• LimitsDefinitionCrudRestService.java:
  • /structure/save
  • /structures/save
  • /limit/save
  • /limits/save

ROLE_USER no longer required in Atoti Limits

ROLE_USER is no longer a required role for all users in Atoti Limits. Previously, this role was required because it was hardcoded as the owner/reader of KPIs created by Atoti Limits. Now, the role set as the owner/reader of KPIs created by Atoti Limits is auto-configured, or can be overridden using the limits.autoconfiguration.content-server.limits-created-measures-owners property. Users will need to have this auto-configured (or overridden) role, or a data access role, to view KPIs created by Atoti Limits, including the calculated members related to the KPIS.

If users have trouble accessing KPIs and calculated measures after upgrading to this version, you may need to manually delete them from the content server so Atoti Limits can recreate them with the correct owner/reader role(s).

Temporary limits changes

The following changes have been made involving temporary limits:

1. sourceLimitId field is now validated for temporary limits

The sourceLimitId field links a temporary limit to its source limit. This field is now validated to ensure that the source limit exists and is an official limit. Please ensure that the sourceLimitId field is correctly set when creating temporary limits.

2. Temporary limits are now grouped under official limits

Limits retrieved via REST now have temporary limits grouped under the official limit indicated in the temporary limit’s sourceLimitId field. If you are using the Atoti Limits REST API to retrieve limits, please note that you may need to update your code to account for this change. Temporary limits are stored in the temporaryLimits field of the corresponding official limit.

Auto-configuration changes

We have updated some of our @Autoconfiguration classes to not explicitly @Import Spring beans and to instead use the @ConditionalOnMissingBean annotation to check for the presence of the beans. This makes it easier for users to inject beans into Atoti Limits and prevents the need to mark a bean as @Primary when multiple beans are present.

The following @AutoConfiguration classes have had explicit imports removed:

• LimitsCoreAutoconfiguration
• LimitsEvaluationServicesAutoConfiguration

The following beans are now @ConditionalOnMissingBean:

• DefaultUtilizationMeasureCalculator which implements IUtilizationCalculator
• LimitsCopperMeasureBuilder which implements ILimitsCopperMeasureBuilder
• DefaultEvaluationService which implements IEvaluationService

If you have any custom implementations of these interfaces then you can remove the @Primary annotation.