Migration guide 4.0

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

Migrate to 4.0.4

Summary

• Recommended performance enhancement: Disable scope hierarchies for large cardinalities of limit scopes.
• Warning Threshold: Intrepretation of the warning threshold limit has been updated.

Disabling scope hierarchies

The scope level name and scope level member hierarchies can incur a performance cost when using Atoti Limits with limits with a high cardinality of scopes. We recommend disabling scope hierarchies if you do not require these hierarchies to improve the overall performance of Atoti Limits. This can be done by setting the property limits.cube.scope-hierarchies-enabled=false in the application.yml file of your Atoti Limits application.

Warning threshold

In version 4.0.1, 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.0.1-4.0.3, 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.0.3

Summary

This is a maintenance release that includes bug fixes and performance improvements.

Deprecations

ILimitsActivitiAuthenticationManager

The ILimitsActivitiAuthenticationManager interface is no longer used, has been deprecated and marked for removal. This interface was previously used to authenticate requests to the Activiti engine in threads spawned by the DLC. It is no longer used and the authentication is now managed by the DelegatingSpringSecurityContextDataLoadController. It will be removed in the next minor release.

IWebClientService

The getWithAuth(...) methods in IWebClientService have been deprecated and marked for removal. These are no longer invoked and the default implementations of these methods in WebClientService now throw an UnsupportedOperationException.

The get(...) methods are now used instead.

If you have custom code that calls the getWithAuth(...) methods you will need to update it to use the get(...) methods instead.

ConnectedAtotiServer and ConnectedAtotiServersManager deprecations

The following fields have been deprecated and marked for removal in ConnectedAtotiServer and ConnectedAtotiServersManager. These are no longer required because the ILimitsRestClientBuilderProvider is responsible for authenticating requests, so we don’t need to pass these variables through the application.

ConnectedAtotiServer fields:

• authentication
• limitsAuthentication
• servicePrincipal
• useJwtMachineToMachineAuth

ConnectedAtotiServersManager fields:

• contentServerAuth
• limitsAuth
• servicePrincipal
• useJwtMachineToMachineAuth

Configuration properties

Properties deprecated

limits-integration-common module

Migrate to 4.0.2

Summary

• WebClientService changes
• Calculated measure location

WebClientService changes

If you previously extended WebClientService, update it to implement the new IWebClientService interface. The methods are unchanged, but Atoti Limits now references IWebClientService instead of WebClientService.

/**
 * <b>IWebClientService</b>
 *
 * <p>This service is used to send authenticated requests from the Atoti Limits Server to
 * application servers.
 *
 * @author ActiveViam
 */
public interface IWebClientService {

  /**
   * Sends a POST request with the {@link RestClient} API.
   *
   * @param serverName - The target server for this {@link RestClient}'s Http requests
   * @param path - The path of the endpoint receiving the request
   * @param jsonBody - The POST request's payload body
   * @param errorMessage - A custom error message if an exception occurs
   * @return The POST response as a String
   */
  String post(String serverName, String path, String jsonBody, String errorMessage);

  /**
   * Sends a POST request with the {@link RestClient} API.
   *
   * @param serverName - The target server for this {@link RestClient}'s Http requests
   * @param path - The path of the endpoint receiving the request
   * @param jsonBody - The POST request's payload body
   * @param errorMessage - A custom error message if an exception occurs
   * @param extractResponseBody - If true, construct a {@link JsonErrorException}, else, throw a
   *     {@link LimitsWebClientServiceException}
   * @return The POST response as a String
   */
  String post(
      String serverName,
      String path,
      String jsonBody,
      String errorMessage,
      boolean extractResponseBody);

  /**
   * @param url - The {@code url} of the endpoint receiving the request
   * @param server - The target server for this {@link RestClient}'s Http requests
   * @param errorMessage - A custom error message if an exception occurs
   * @return The GET response as a String
   */
  String get(String url, String server, String errorMessage);

  /**
   * @param url - The {@code url} of the endpoint receiving the request
   * @param server - The target server for this {@link RestClient}'s Http requests
   * @param errorMessage - The custom error message if an exception occurs
   * @param extractResponseBody - If true, construct a {@link JsonErrorException}, else, throw a
   *     {@link LimitsWebClientServiceException}
   * @return The GET response as a String
   */
  String get(String url, String server, String errorMessage, boolean extractResponseBody);

  /**
   * @param url - The {@code url} of the endpoint receiving the request
   * @param authorization - The encoded {@code authorization} string
   * @param errorMessage - The custom error message if an exception occurs
   * @return The GET response as a string
   */
  String getWithAuth(String url, String authorization, String errorMessage);

  /**
   * Makes a GET request with the authentication already encoded. This method is called when sending
   * requests to the RemoteContentServer, which doesn't have a `serverName` but already has an
   * encodedAuth string.
   *
   * @param url - The {@code url} of the endpoint receiving the request
   * @param authorization - The encoded {@code authorization} string
   * @param errorMessage - A custom error message if an exception occurs
   * @param extractResponseBody - If true, construct a {@link JsonErrorException}, else, throw a
   *     {@link LimitsWebClientServiceException}
   * @return The GET response as a String
   */
  String getWithAuth(
      String url, String authorization, String errorMessage, boolean extractResponseBody);

  /**
   * Sends a PUT request with the {@link RestClient} API.
   *
   * @param serverName - The target server for this {@link RestClient}'s Http requests
   * @param path - The path of the endpoint receiving the request
   * @param body - The PUT request's payload body
   * @param responseType - The expected response type
   * @return The PUT response as a String
   */
  <T> ResponseEntity<T> put(String serverName, String path, Object body, Class<T> responseType);
}

Calculated measure location

If you have limits on calculated measures, we expect that these calculated measures are saved in either the /pivot/entitlements/cm folder of the content server (recommended) OR in the ui/calculated_measures folder (not recommended). If you have limits on calculated measures that exist in both folders, then those in ui/calculated_measures should be moved to /pivot/entitlements/cm, otherwise these limits won’t be created. The ui/calculated_measures folder is the location for calculated measures that were saved via ActiveUI 4, so we do not expect most users will need to migrate.

Configuration files

Files Modified

Properties added

limits-activeviam module

limits-integration-common module

Migrate to 4.0.1

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

Summary

• Disable Scope Hierarchies: We have added a property limits.cube.scope-hierarchies-enabled that can be used to disable scope hierarchies to improve loading performance for large cardinalities of limit scopes.
• Roles: ROLE_USER no longer required in Atoti Limits.

Configuration files

Files Modified

Properties added

limits-activeviam module

Other changes

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.

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.

Summary

• 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:

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:

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

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:

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:

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

Properties modified

limits-activeviam module

limits-integration-common module

limits-atoti-server-61

Properties deleted

Property files

No changes.

Datastores

Modified stores

Cube schema

Added

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.