Migration notes - Atoti Hub

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

Please note that Atoti Server versions 5.9 and 5.10 are now out-of-support. Therefore, we will no longer support connections to servers of these versions as of the next release of Atoti Limits.

Migrate to 3.2.0

Upgrading from version 3.1.0, see the Atoti Limits 3.2.0 Release Notes. Atoti Limits is using Atoti Server 6.0.12-sb3 and Atoti UI 5.1.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.0.12-sb3.
Spring Boot upgrade : We have upgraded Spring Boot to version 3.2.0, which uses Spring Framework 6. See Spring Boot 3 upgrade for more details.
Common Parent POM and Common Dependencies BOM upgrade: The Common Parent POM and the Common Dependencies BOM have both been upgraded to version 2.0.0.
Activiti upgrade : We have upgraded Activiti to version 8.1.0 to be compatible with Spring Boot 3. See Activiti upgrade for more details.
Changes to LimitsRetrievalUtil: The LimitsRetrievalUtil class, which previously contained static methods, has been converted to a Spring service name LimitsRetrievalService. If used in custom code then the methods of this class will need to be updated. For details, see Changes to LimitsRetrievalUtil.
UI Activation : An import of react-query is required when using limits-sdk. See UI activation for more details.
Spotify Code Formatter : We now use Spotify’s code formatter plugin to format and validate our code. For more details, see Spotify Code Formatter.

Breaking changes

Upgrades:
- The version of Spring Boot has been upgraded to version 3.2.0, which includes breaking changes. See the Spring migration guide for more information.
- In order to be compatible with Spring Boot 3.2.0 we have upgraded Activiti to version 8.1.0. This requires including extension.json files with each workflow file. See Activiti upgrade for more information.

Spring Boot 3 upgrade

The main change in the Spring Boot 3 upgrade involves migrating javax.** imports to jakarta.xx imports.

Limits Auto-Configuration

In order for the Limits auto-configuration to work with Atoti Server using Spring 5 and Spring 6, the context path of the application is now derived from Spring’s server.servlet.context-path variable instead of from the application runtime. No migration is required unless you specify your context path in another way. If so, we recommend you use the server.root.url specified in Auto-configuration properties.

Activiti upgrade

Extension JSON files

In order to upgrade Activiti, you now need to supply an **-extensions.json file for each of your workflows. These extension files externalize information about the workflow and provide it to Activiti’s runtime engine. An example of some of the contents in the **-extension.json file may look as follows:

{
   "id": "PROCESS",
   "name": "PROCESS",
   "extensions": {
      "limit-process-instance.straight-through": {
         "properties": {},
         "mappings": {
            "start.event": {
               "mappingType": "MAP_ALL"
            },
            "approvedUserTask": {
               "mappingType": "MAP_ALL"
            },
            "deletedServiceTask": {
               "mappingType": "MAP_ALL"
            },
            "flow1": {
               "mappingType": "MAP_ALL"
            }
         },
         "constants": {}
      }
   }
}

In the example above:

limit-process-instance.straight-through corresponds to the ID of a process definition. This maps to a single BPMN file.
start.event corresponds to the ID of a Start Event.
approvedUserTask corresponds to the ID of a User Task.
deletedServiceTask corresponds to the ID of a Service Task.
flow1 corresponds to the ID of a Sequence Flow.
"mappingType": "MAP_ALL" tells Activiti to map all input and output variables throughout the workflow.

When upgrading, we added mappings for all Start Events, User Tasks, Service Tasks and Sequence Flows, and you will have to do the same for any custom workflows or customizations to our default workflows.

Custom Task Action Delegator

If you are customizing the IWorkflowTaskActionDelegator as outlined in Executing the Java Task, you may need to reload the LimitStructureDTO. Please see the DefaultWorkflowTaskActionDelegator::executeTaskActionForTaskActionKey method for an example of how this is done.

Changes to LimitsRetrievalUtil

The LimitsRetrievalUtil class has been converted to a Spring service named LimitsRetrievalService, which implements the ILimitsRetrievalService interface, to make our code more Spring-compliant. If you have custom code that used this class, you will need to update that code. A summary of the changes are as follows:

Many of the methods have been replaced by their corresponding new methods in ILimitsRetrievalService. The most commonly used methods are:
- getLimitStructures()/getLimits() - to get the limit structures/limits.
- getLimitStructure(int limitStructureKey)/getLimit(int limitKey) - to get a specific limit structure/limit by its key.
- getLimitStructure(LimitsQueryPayload limitsQueryPayload)/getLimit(LimitsQueryPayload limitsQueryPayload) - to get a specific limit structure/limit filtered by a payload object.
- getLimitStructures(LimitsQueryPayload limitsQueryPayload)/getLimits(LimitsQueryPayload limitsQueryPayload) - to get limit structures/limits filtered by a payload object.
We have added a new LimitsQueryPayload class to allow for more complex filtering of limits and limit structures. This class is used in the new methods mentioned above.
The methods have been made non-static. As such, to access the methods, inject the service where you need it and publicly invoke the methods. For cases when injection is not possible, for example in code outside your control, we have added the ApplicationContextProvider bean, which allows you to statically retrieve the service. See the LimitsLoadDataTxControllerTask::initializeSpringBeans method as an example of how you may do so.
The datastoreVersion parameter is now specified by assigning a value to the branchName field in LimitsQueryPayload.
The term limitDefinition present in some methods has been renamed to limitStructure, to update old terminology. For example, the getLimitDefinitions() method is now named getLimitStructures().
The term limitEvaluation present in some methods has been renamed to limit, to update old terminology. For example, the getLimitEvaluations() method is now named getLimits().
When implementing a custom IAlertTaskManager, you now need to override the getLimitsRetrievalService() method.

WebClientService

All HTTP requests made by Atoti Limits have been extracted into WebClientService and use Spring’s RestClient

Property relocation

The workflow properties that were previously defined in the UI settings have now been moved to the server side in application.yml, namely:

exceptionWorkflowParticipants
limitsWorkflowParticipants
roles

Please see below for the new properties.

Input file formats

Modified

Modification	File	Field	Optional	Description
Added	limits_approve.csv	Precedence	Y	Numerical value to override which limit in a limit structure should be used for evaluation. A higher value indicates higher precedence. Field moved from the limit_structures.csv input file.
Deleted	limit_structures.csv	Precedence	Y	Numerical value to override which limit in a limit structure should be used for evaluation. A higher value indicates higher precedence. Field moved to the limits_approve.csv input file.

Configuration files

Files Modified

application.yml

New properties:

Property Name	Comment	Value
limits.limitWorkflows.StraightThrough.key	Renamed from limits.workflow-types.StraightThrough	limit-process-instance.straight-through
limits.limitWorkflows.FourEyes.key	Renamed from limits.workflow-types.FourEyes	limit-process-instance.four-eyes
limits.limitWorkflows.SixEyes.key	Renamed from limits.workflow-types.SixEyes	limit-process-instance.six-eyes
limits.exceptionWorkflows.Exception.key	Renamed from limits.workflow-types.Exception	limit-process-instance.exception
limits.limitWorkflows.FourEyes.participants	Contains a comma-separated list of reviewers for the FourEyes workflow	Approvers
limits.limitWorkflows.SixEyes.participants	Contains a comma-separated list of reviewers for the SixEyes workflow	Examiners,Approvers
limits.roles	Contains a comma-separated list of security roles, applicable to any workflow	ROLE_USERS,ROLE_MANAGERS

Deleted properties:

Property Name	Comment
limits.workflow-types.StraightThrough	Property has been replaced with object containing the workflowKey and list of `participants`. See the new property structure here, application.yml
limits.workflow-types.FourEyes	Property has been replaced with object containing the workflowKey and list of `participants`. See the new property structure here, application.yml
limits.workflow-types.SixEyes	Property has been replaced with object containing the workflowKey and list of `participants`. See the new property structure here, application.yml
limits.workflow-types.Exception	Property has been replaced with object containing the workflowKey and list of `participants`. See the new property structure here, application.yml
limits.workflow-types.Deletion	Property has been removed because the `Deletion` is not a supported workflow.
limit.csv.load.mode	The legacy file upload was removed, so this property is no longer required.

Datastores

Modified stores

Modification	Store	Field	Type	Description
Deleted	Limit Structures	Exception Category	String	Removed this unused field.
Deleted	Limit Structures	Exception Comment	String	Removed this unused field.
Deleted	Incidents	Comment	String	Removed this unused field.
Deleted	Limit Structures	Precedence	int	Moved this field to the Limits store.
Added	Limits	Precedence	int	Moved this field from the Limit Structures store.
Renamed	Incidents	None	None	Renamed `IncidentsStore` to `Incidents`
Renamed	AsOfDate	None	None	Renamed `AsOfDateStoreName` to `AsOfDate`
Renamed	Scope Keys	None	None	Renamed `ScopeKeysStore` to `ScopeKeys`
Renamed	Scope Values	None	None	Renamed `ScopeValuesStore` to `ScopeValues`

Cube schema

Added

Cube	Dimension	Hierarchy	Levels	Datastore fields	Details
Limits	Limit	Scope (Full)	Scope (Full)	N/A	The full string representation of the scopes present in the cube, which will include dimension and hierarchy information.

Measures

Removed

Cube	Measure	Details
Limits	Scope	This scope measure has been replaced with the `Scope` level.

Context values

No changes.

Other changes

Spotify Code Formatter

We now use Spotify’s code formatter plugin to format and validate our code. To format your code you, may use the format Maven profile, for example by running mvn clean install -P format. To validate that your code is correctly formatted as per the plugin, which uses Google’s code standards, you may use the validate Maven profile, for example by running mvn clean install -P validate.

Changes to ILimitsProcessInstanceWorkflowService

If you implement a custom ILimitsProcessInstanceWorkflowService, modify the initiate method to match the new signature.

Old signature	New signature
`AHistoryRecordDTO initiate(LimitsProcessInstanceDTO object, String comment, boolean refreshKpis)`	`AHistoryRecordDTO initiate(LimitsProcessInstanceDTO instanceObject, String comment, boolean publishTuples, boolean refreshKpis)`

The new publishTuples parameter determines if updated tuples should be published immediately to the datastore. If false, the invoker of this method should manually publish tuples after the method completes. This is more performant for large updates.

Documentation Index

​Migrate to 3.2.0

​Headline announcement

​Breaking changes

​Spring Boot 3 upgrade

​Limits Auto-Configuration

​Activiti upgrade

​Extension JSON files

​Custom Task Action Delegator

​Changes to LimitsRetrievalUtil

​WebClientService

​Property relocation

​Input file formats

​Modified

​Configuration files

​Files Modified

application.yml

​Datastores

​Modified stores

​Cube schema

​Added

​Measures

​Removed

​Context values

​Other changes

​Spotify Code Formatter

​Changes to ILimitsProcessInstanceWorkflowService

Migrate to 3.2.0

Headline announcement

Breaking changes

Spring Boot 3 upgrade

Limits Auto-Configuration

Activiti upgrade

Extension JSON files

Custom Task Action Delegator

Changes to LimitsRetrievalUtil

WebClientService

Property relocation

Input file formats

Modified

Configuration files

Files Modified

Datastores

Modified stores

Cube schema

Added

Measures

Removed

Context values

Other changes

Spotify Code Formatter

Changes to ILimitsProcessInstanceWorkflowService