Migration notes 4.0

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

Migrate to 4.0.0

Upgrading from version 3.3.0, see the Atoti Limits 4.0.0 Release Notes.

Atoti Limits is using Atoti Server 6.1.1 and Atoti UI 5.2.x.

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.

Headline announcement

• Atoti Server upgrade : Atoti Limits has been upgraded to Atoti Server 6.1.1. For the required changes, see Atoti Server upgrade.
• Atoti UI upgrade : Atoti UI has been upgraded to version 5.2.0. For the required changes, see the Atoti UI migration guide.
• Maven Artifact group ID changes: The groupIDs for maven artifacts have been updated from com.activeviam.limits to com.activeviam.solutions.limits to align with other ActiveViam Business Solutions. Please update your groupIDs when importing Atoti Limits artifacts. This change does not affect package names.
• Improvements to the auto-configuration modules : These improvements require you to update dependencies and properties.
• Simplified scopes migration script : We have added an optional script for migrating CSV files to use the simplified scope notation. See CSV migrations to 4.0.0.

Breaking changes

• Starter changes : Multiple classes have been removed from the starter module. See Starter changes for more details.
• Removal of DTO suffix : The “DTO” suffix has been removed from Java objects that were not pure data transfer objects. See the full list of changes below.
• Manual configuration removal : Manual configuration has been removed in favor of auto-configuration.

Atoti Server upgrade

For details on migrating your code to Atoti Server 6.1.1, see the Atoti Server migration notes.

Here are the main changes you need to make to your Atoti Limits code:

Java 21

Update your Java version to Java 21 or later in order to run Atoti Limits.

Atoti Spring Boot Starter changes

Atoti Server now ships with a suite of Spring Boot Starters. These dependencies auto-configure default imports required by Atoti Server, that you may override at runtime.

If you do not use the out-of-the-box limits-starter, import these starter dependencies and remove any explicit import of classes that are now auto-configured. If you do use the out-of-the-box limits-starter, no further changes are required.

The following core classes have been removed in limits-activeviam or limits-starter as they are now inherited from starters:

• ActivePivotServicesConfig.class
• ActivePivotWebSocketServicesConfig.class
• ActivePivotWithDatastoreConfig.class
• ActivePivotXmlaServletConfig.class
• ActiveViamRestServicesConfig.class
• AdminUIResourceServerConfig.class
• AtotiServerWebMvcConfigurer.class
• ContentServerWebSocketServicesConfig.class
• FullAccessBranchPermissionsManagerConfig.class
• JwtConfig.class
• LocalI18nConfig.class
• NoSecurityDatabaseServiceConfig.class
• TracingConfig.class

Security configuration changes

The upgrade to Atoti Server 6.1.1 includes changes to the security configuration. We expect you to implement your own security, but we provide a sample configuration in the com.activeviam.limits.starter.cfg.security package.

For details on how to implement your own security, please see the Atoti Server documentation.

Starter changes

Most of the limits-starter module has been moved into limits-activeviam. The goal of these changes is ultimately to improve the developer experience when migrating, particularly in the context of client customizations. Please see the Recommended custom project structure for more details on how to structure your project.

To this end, we have made the following changes:

• We have added a new LimitsCoreAutoConfiguration class in limits-activeviam. This is a base configuration class for the imports required by Atoti Limits and is auto-configured on startup.
  • Most of LimitsAppConfig has been moved to LimitsCoreAutoConfiguration.
• LimitsApplicationConfigurationPropertiesConfig has been removed and the properties have been moved into the @EnableConfigurationProperties annotation in LimitsCoreAutoConfiguration.
• We have added a new LimitsRestServicesAutoConfiguration class to import all the REST services required by Atoti Limits.
• LimitsProcessExceptionHandler has been removed and the exception handlers it contained have been merged into RestExceptionHandlerControllerAdvice.

We have converted many of the *Config classes explicitly imported in LimitsAppConfig to *AutoConfiguration classes and moved them to the com.activeviam.limits.autoconfigure package in limits-activeviam. These new classes will be automatically registered via Spring Auto-configuration, so there is no more need to explicitly import them. The beans that were exposed by these classes are now annotated with @ConditionalOnMissingBean, so you can define your own implementations of the interfaces to override the default beans. The following classes have been affected by this change:

Old *Config class	New *AutoConfiguration class	Description
DefaultManagedObjectIdentityGeneratorConfig	ManagedObjectIdentityGeneratorAutoConfiguration	Configuration for the ID generators.
EvaluationServiceConfig	LimitsEvaluationServicesAutoConfiguration	Configuration for the services used when evaluating limits.
LimitsContentConfig	ContentServiceAutoConfiguration	Configurations for the content service.
LimitsDatastoreConfig	LimitsDatastoreAutoConfiguration	Configuration for the datastores.
LimitsValidationConfig	LimitsValidationAutoConfiguration	Configuration for the validation API.
LimitsWorkflowConfig	LimitsWorkflowAutoConfiguration	Configurations for the workflow.
PivotConfig	LimitsManagerAutoConfiguration	Configuration for the services used when evaluating limits.

The following classes have been moved from LimitsAppConfig to LimitsCoreAutoConfiguration:

• LimitsActivitiAuthenticationManager,
• LimitsDataProperties
• LimitsDimensionsConfig
• LimitsCubeConfig
• LimitsAsOfDateLoader
• DataLoadControllerConfig
• CSVSourceConfig
• LimitsProcessEngineMailConfig
• ConnectedAtotiServersManager (previously RemoteAtotiServersProperties)
• LimitsManagerConfig (previously PivotConfig)

The following classes have been moved from LimitsAppConfig to the new LimitsRestServicesAutoConfiguration class:

• AutoConfigRestService
• DataLoadControllerRestServiceConfig
• IncidentRestController
• IncidentsSseController
• KPICrudRestService
• LimitsAsOfDateRestService
• LimitsDefinitionCrudRestService
• LimitsEvaluationRestService
• LimitsServerSettingsRestController
• RemoteCubeRestService
• RestExceptionHandlerControllerAdvice
• ScopeRetrievalRestService
• UploadCsv

The following classes have been moved from LimitsAppConfig to the new LimitsDatastoreAutoConfiguration class:

• AtotiServerWithDatastoreConfig
• DatastoreConfiguratorSetup
• LimitsDatastoreService
• LimitsDatastoreVersionService
• LimitsDefinitionDatastoreConfig
• LimitsProcessInstanceDatastoreConfig
• LimitsSchema
• ScopeTupleGenerator
• TuplePublisherConfig

The following classes have been moved from LimitsAppConfig to the new LimitsCrudServicesAutoConfiguration class:

• IncidentCrudService
• KpiCrudService
• LimitsCrudService
• LimitsRetrievalService

The following classes have been moved from LimitsAppConfig to the new LimitsEvaluationServicesAutoConfiguration class:

• DefaultEvaluationService
• DefaultEvaluationTaskManager
• EvaluationErrorHandler

The following classes have been moved from LimitsAppConfig to the new LimitsJpaAutoConfiguration class:

• LimitsJpaConfig
• LimitsProcessJpaConfig

The following classes have been moved from LimitsAppConfig to the new LimitsPersistenceServicesAutoConfiguration class:

• DefaultLimitsAppCrudService
• DefaultLimitsAppDatastoreCrudService

The following classes have been renamed:

Old class name	New class name
PivotManager	LimitsManagerDescriptionConfig

Improvements to the auto-configuration modules

Although we do not intend for these modules to be extended, we have made improvements to the auto-configuration modules that are breaking.

You won’t need to update code, but you’ll need to update dependencies and properties. For more information see the connected server section.

Changes requiring action

Breaking change	Action required
The limits-auto-config-ap<ATOTI_SERVER_VERSION_PREFIX> artifacts have been renamed to limits-auto-config-<ATOTI_SERVER_VERSION_PREFIX>.	Update your dependency import.
The limits-auto-config modules are now true auto-configuration modules, meaning you now only have to import the dependency, not the classes.	Remove the previous import of LimitsAutoConfig.
The old autoconfiguration properties have been replaced with new properties.	Update your properties accordingly. note Only four properties are marked as REQUIRED.

Changes not requiring action

• LimitsAutoConfig has been renamed to LimitsConnector.
• RemoteAtotiServersProperties was used in the past to store the connected servers in Atoti Limits and as a configuration source for the manual configuration. As we have removed the manual configuration, it has been renamed to ConnectedAtotiServersManager.
• The com.activeviam.limits.autconfig.* packages have been renamed to com.activeviam.limits.autoconfigure.*.
• The com.activeviam.limits.integration.common.* packages have been renamed to com.activeviam.limits.autoconfigure.common.*.
• The limits-auto-config-ap<ATOTI_SERVER_VERSION_PREFIX> artifacts have been renamed to limits-auto-config-<ATOTI_SERVER_VERSION_PREFIX>.
• The lookup-post-processor-ap<ATOTI_SERVER_VERSION_PREFIX> artifacts have been renamed to lookup-post-processor-<ATOTI_SERVER_VERSION_PREFIX>.

Artifact changes

We have reorganized the artifacts used by the connected server to connect with Atoti Limits.

This includes artifacts for connecting with instances of Atoti Server on version 6.0.x using Java 11, in addition to the already supported 6.0.x-sb3 version using Java 17.

The limits-shared-properties module has been renamed to limits-common and the limits-lookup-postprocessors modules have been merged into the limits-integration and limits-common modules. This helps:

• reduce the number of modules in the project,
• simplify the usage of Spring in the LookUpPostProcessor,
• facilitate future improvements by having more reusable code across Atoti Server version-specific modules.

The artifact structure is as follows:

• limits
  • limits-activeviam - Source code for the services required by Atoti Limits.
  • limits-atoti-server - An Atoti Server sandbox used for testing Atoti Limits. Not intended for production.
    • limits-atoti-server-60 - Atoti Server sandbox running on 6.0.X.
    • limits-atoti-server-60-sb3 - Atoti Server sandbox running on 6.0.X-sb3.
    • limits-atoti-server-61 - Atoti Server sandbox running on 6.1.X.
  • limits-integration - Code to integrate Atoti Server with Atoti Limits.
    • limits-auto-config-60 - Code to integrate Atoti Server with Atoti Limits 6.0.X.
    • limits-auto-config-60-sb3 - Code to integrate Atoti Server with Atoti Limits 6.0.X-sb3.
    • limits-auto-config-61 - Code to integrate Atoti Server with Atoti Limits 6.1.X.
  • limits-migrations - Scripts to migrate Atoti Limits.
  • limits-common - Code common to both limits-activeviam and limits-integration modules.
  • limits-starter - Lightweight Spring Boot application used to get Atoti Limits up and running quickly.

The artifact changes from the previous release are as follows:

Old Name	New Name	Comment
limits-shared-properties	limits-common	The old artifact has been renamed.
limits-common-lookup	limits-common	The old artifact has been merged into the new artifact.
lookup-post-processor-ap60	limits-auto-config-60-sb3	The old artifact has been merged into the new artifact and requires Java 17.
N/A	limits-auto-config-60	This new artifact is compatible with Java 11.
limits-auto-config-ap60	limits-auto-config-60-sb3	The old artifact has been renamed and requires Java 17.
limits-atoti-server-60	limits-atoti-server-60-sb3	The old artifact has been renamed and requires Java 17.
N/A	limits-atoti-server-60	This new artifact is compatible with Java 11.

Removal of DTO suffix

We have removed the “DTO” suffix from classes that were not pure data transfer objects. Please update any references to these classes in your custom code:

• LimitDTO.java
• LimitStructureDTO.java
• IncidentDTO.java
• LimitsProcessInstanceDTO.java
• HistoricalClassDifferenceDTO.java
• HistoricalFieldDifferenceDTO.java
• CalculatedMeasureDTO.java
• CalculatedMeasuresDTO.java
• ContentServerElementDTO.java
• ContentServerEntryDTO.java

CSV migrations to 4.0.0

The migration script migrates the limits.csv files from Atoti Limits 3.3.0 to 4.0.0 by converting the scope value to the new simplified notation.

How it works

This script expects the following program arguments (in this order):

1. The target version of Atoti Limits (should be 4.0.0).
2. The source limits input file path.
3. The target limits output file path.

Steps

1. Run mvn clean install on limits-migrations.
2. Run java -jar path/to/limits-migrator-tool-exec.jar 4.0 path/to/source/limits.csv path/to/target/limits.csv path/to/properties/folder.
   Your files are now converted to the new format and can be found in the target directory.
   

   note

   The output directory must already exist, but the file will be created.

Changes to ILimitsRetrievalService

The ILimitsRetrievalService interface has been updated and the default implementation, LimitsRetrievalService, has been significantly changed to improve performance. If you have implemented a custom version of this service, you will need to make the following method changes:

Old signature	New Signature	Note
ILimitsDatastoreVersionService getLimitsDatastoreVersionService();	N/A	This method has been removed.
IDatabaseVersion getDatastoreVersion(LimitsQueryPayload limitsQueryPayload);	IDatabaseVersion getDatastoreVersion(String branchName);	This method has been modified to accept a string argument specifying the name of the branch on which to execute the query.
Integer getPendingApprovalsForLimitStructure(String limitStructureId);	Map<String, Integer> getPendingApprovalsForLimitStructure(Set<String> limitStructureIds);	This method has been updated to accept a set of limit structure IDs and return a map of those IDs to the number of pending approvals. This improves performance for UI requests on the Inventory screen.

Removing manual configuration

The manual configuration has been removed from Atoti Limits. Please see the removed properties table for the properties you should remove.

Validator API changes

Several API changes have been made to the IValidator interface:

• The ILimitValidator, ILimitStructureValidator, and IIncidentValidator interfaces have been moved to the com.activeviam.limits.model.validation.function.intf package.
• The getInvalidObjects() method has been removed since it was not used.
• The reset(boolean throwException) method has been updated to an empty default implementation and is overridden by the abstract class, AValidator. To override the reset method, see the custom validator page for more information.

Removing Between and Not Between KPI types

The Between and Not Between Kpi types have been removed as valid KPI types since they were never supported by Atoti Limits.

Configuration

Configuration properties

Files Modified

limits-integration-common module

All properties have been replaced. Please see the new properties for the updated list.

limits-activeviam module

Properties added

limits-activeviam module

Property	Default value	Description
limits.cube.format.kpi-goal	#,##0.#	Format value for KPI Goal values.
limits.cube.kpi-filters-enabled	true	True if cube filters are enabled for Limits KPIs, false otherwise.
limits.data-access-control.servers..role-permissions		Defines the permissions available to each role.
limits.data-access-control.servers..default-scope-match-mode	MATCH_ALL	Sets the match mode to use for scope permissions when it is omitted.
limits.autoconfiguration.content-server.limits-created-measures-owners		The roles that will be the owner/reader for the calculated members that were created based on the KPIs. The value should be auto-configured from the KPI owners in the content server.
limits.workflow.workflow-status-fetched-with-limit	true	When set to true, retrieving limit structures also updates the limit status with the current workflow status.

Properties modified

limits-activeviam module

Property Name	Comment	New Value	Old Value
limits.limit-workflows.*	Added token to root.	limits.workflow.limit-workflows.*	limits.limit-workflows.*
limits.exception-workflows.*	Added token to root.	limits.workflow.exception-workflows.*	limits.exception-workflows.*
limits.workflow-rules.*	Added token to root.	limits.workflow.workflow-rules.*	limits.workflow-rules.*
limits.roles.*	Added token to root.	limits.workflow.roles.*	limits.roles.*

limits-integration-common module

Property Name	Comment	New Value	Old Value
limits.autoconfiguraton.limits-base-url	The base URL of the Limits server.	limits.autoconfiguraton.limits-base-url
limits.autoconfiguraton.atoti-base-url	The base URL of the connected Atoti Server.	limits.autoconfiguraton.limits-base-url	limits.autoconfiguraton.root-url

limits-atoti-server-61

Properties deleted

Property Name	Comment
content.*	All properties for the Atoti Limits content server have been removed as it is not used.
limits.connected-server.*	These properties used for manual configuration have been removed.
limits.content.server.*	These properties used for manual configuration have been removed.
limits.rest-url	This property used for manual configuration has been removed.
limits.auth	This property used for manual configuration has been removed.

Property files

No changes.

Datastores

Modified stores

Modification	Store	Field	Type	Description
Added	Limits	Alive	Boolean	This field indicates whether the limit is still alive (not deleted or expired). For more details, see Alive field in Limits store.

Cube schema

Added

Cube	Dimension	Hierarchy	Levels	Datastore fields	Details
Limits	Limit	Scope Level Name	Scope Level Name	ScopeKeys	The level name of a limit’s scope, for example Book@Books@Booking.
Limits	Limit	Scope Level Member	Scope Level Member	ScopeValues	The level member of a scope, for example Book 1.

Measures

No changes.

Other changes

Independent retrieval of limit status

/limits/rest/v2/limitDefinition/limits/status/get retrieves status of Limits based on their id. This completes the server setting workflow-status-fetched-with-limit to omit status when fetching limits structures with /limits/rest/v2/limitDefinition/structure/get.

This helps loading the limits viewer screen in the Atoti UI when the amount of Limits in a structure is relatively large. If a long time is experienced when fetching the Limits in the UI (more than a few seconds) this aims at retrieving the Limits faster by decoupling the retrieval of each Limit’s status.

Alive field in Limits store

Due to the independent retrieval of limit status, a field has been added to the Limits store to keep track of whether a limit is alive (not expired or deleted). This was previously based on the status of the limit, which was stored in the Limits store. However, the status is now exclusively retrieved through the workflow, so information on whether a limit is alive is now independent of the status, so it can be retrieved at a later stage.

This store field defaults to true and cannot be set via CSV source as we expect any limit loaded from file existing at its creation. To access a deleted or expired limit, it should be persisted in the audit trail.

ROLE_LIMITS is no longer a required role

The ROLE_LIMITS role is no longer required for all users of Atoti Limits. This role has been repurposed as the full-access role in the permission roles to maintain backward compatibility. Users with this role will continue having full access to all actions in the UI as they previously did.