> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration notes

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

<Warning>
  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.
</Warning>

## Migrate to 3.2.0

Upgrading from version *3.1.0*, see the [Atoti Limits 3.2.0 Release Notes](../../release-notes#320).

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](https://docs.activeviam.com/products/atoti/ui/5.1/)
and [Atoti UI Migration Notes](https://docs.activeviam.com/products/atoti/ui/5.1/docs/changelog), and
the [release notes for Atoti Server](https://docs.activeviam.com/products/atoti/server/6.0.12-sb3/docs/release/changelog/index.).

### 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](#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](#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](#changes-to-limitsretrievalutil).
* **UI Activation** : An import of `react-query` is required when using `limits-sdk`. See [UI activation](../../../dev/dev-ui-config/ui-activation#activating-atoti-limits) 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](#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](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-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](#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:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
   "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:

1. 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.
2. 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.
3. 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.
4. The `datastoreVersion` parameter is now specified by assigning a value to the `branchName` field in `LimitsQueryPayload`.
5. 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()`.
6. 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()`.
7. When implementing a custom [`IAlertTaskManager`](../../../dev/evaluation-tasks#the-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](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-restclient)

### Property relocation

The workflow properties that were previously defined in the [UI settings](../../../dev/dev-ui-config/ui-settings#limits-settings) have now been moved to the server side in `application.yml`, namely:

* `exceptionWorkflowParticipants`
* `limitsWorkflowParticipants`
* `roles`

Please see [below](#files-modified) for the new properties.

### Input file formats

#### Modified

<table><thead><tr><th>Modification</th><th>File</th><th>Field</th><th>Optional</th><th>Description</th></tr></thead><tbody><tr><td>Added</td><td><a href="../../../user-ref/input-files/limits_approve">limits\_approve.csv</a></td><td>Precedence</td><td>Y</td><td>Numerical value to override which limit in a limit structure should be used for evaluation. A higher value indicates higher precedence.<br />Field moved from the <a href="../../../user-ref/input-files/limit_structures">limit\_structures.csv</a> input file.</td></tr><tr><td>Deleted</td><td><a href="../../../user-ref/input-files/limit_structures">limit\_structures.csv</a></td><td>Precedence</td><td>Y</td><td>Numerical value to override which limit in a limit structure should be used for evaluation. A higher value indicates higher precedence.<br />Field moved to the <a href="../../../user-ref/input-files/limits_approve">limits\_approve.csv</a> input file.</td></tr></tbody></table>

### Configuration files

#### Files Modified

##### [application.yml](../../../user-ref/properties/property-files/application-yml)

New properties:

<table><thead><tr><th>Property Name</th><th>Comment</th><th>Value</th></tr></thead><tbody><tr><td>limits.limitWorkflows.StraightThrough.key</td><td>Renamed from limits.workflow-types.StraightThrough</td><td>limit-process-instance.straight-through</td></tr><tr><td>limits.limitWorkflows.FourEyes.key</td><td>Renamed from limits.workflow-types.FourEyes</td><td>limit-process-instance.four-eyes</td></tr><tr><td>limits.limitWorkflows.SixEyes.key</td><td>Renamed from limits.workflow-types.SixEyes</td><td>limit-process-instance.six-eyes</td></tr><tr><td>limits.exceptionWorkflows.Exception.key</td><td>Renamed from limits.workflow-types.Exception</td><td>limit-process-instance.exception</td></tr><tr><td>limits.limitWorkflows.FourEyes.participants</td><td>Contains a comma-separated list of reviewers for the FourEyes workflow</td><td>Approvers</td></tr><tr><td>limits.limitWorkflows.SixEyes.participants</td><td>Contains a comma-separated list of reviewers for the SixEyes workflow</td><td>Examiners,Approvers</td></tr><tr><td>limits.roles</td><td>Contains a comma-separated list of security roles, applicable to any workflow</td><td>ROLE\_USERS,ROLE\_MANAGERS</td></tr></tbody></table>

Deleted properties:

<table><thead><tr><th>Property Name</th><th>Comment</th></tr></thead><tbody><tr><td>limits.workflow-types.StraightThrough</td><td>Property has been replaced with object containing the workflowKey and list of <code>participants</code>. See the new property structure here, <a href="../../../user-ref/properties/property-files/application-yml">application.yml</a></td></tr><tr><td>limits.workflow-types.FourEyes</td><td>Property has been replaced with object containing the workflowKey and list of <code>participants</code>. See the new property structure here, <a href="../../../user-ref/properties/property-files/application-yml">application.yml</a></td></tr><tr><td>limits.workflow-types.SixEyes</td><td>Property has been replaced with object containing the workflowKey and list of <code>participants</code>. See the new property structure here, <a href="../../../user-ref/properties/property-files/application-yml">application.yml</a></td></tr><tr><td>limits.workflow-types.Exception</td><td>Property has been replaced with object containing the workflowKey and list of <code>participants</code>. See the new property structure here, <a href="../../../user-ref/properties/property-files/application-yml">application.yml</a></td></tr><tr><td>limits.workflow-types.Deletion</td><td>Property has been removed because the <code>Deletion</code> is not a supported workflow.</td></tr><tr><td>limit.csv.load.mode</td><td>The legacy file upload was removed, so this property is no longer required.</td></tr></tbody></table>

### Datastores

#### Modified stores

<table><thead><tr><th>Modification</th><th>Store</th><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Deleted</td><td><a href="../../../user-ref/datastore/limit-structures">Limit Structures</a></td><td>Exception Category</td><td>String</td><td>Removed this unused field.</td></tr><tr><td>Deleted</td><td><a href="../../../user-ref/datastore/limit-structures">Limit Structures</a></td><td>Exception Comment</td><td>String</td><td>Removed this unused field.</td></tr><tr><td>Deleted</td><td><a href="../../../user-ref/datastore/incident-store">Incidents</a></td><td>Comment</td><td>String</td><td>Removed this unused field.</td></tr><tr><td>Deleted</td><td><a href="../../../user-ref/datastore/limit-structures">Limit Structures</a></td><td>Precedence</td><td>int</td><td>Moved this field to the Limits store.</td></tr><tr><td>Added</td><td><a href="../../../user-ref/datastore/limits-store">Limits</a></td><td>Precedence</td><td>int</td><td>Moved this field from the Limit Structures store.</td></tr><tr><td>Renamed</td><td><a href="../../../user-ref/datastore/incident-store">Incidents</a></td><td>None</td><td>None</td><td>Renamed <code>IncidentsStore</code> to <code>Incidents</code></td></tr><tr><td>Renamed</td><td><a href="../../../user-ref/datastore/as-of-date-store">AsOfDate</a></td><td>None</td><td>None</td><td>Renamed <code>AsOfDateStoreName</code> to <code>AsOfDate</code></td></tr><tr><td>Renamed</td><td><a href="../../../user-ref/datastore/scope-keys">Scope Keys</a></td><td>None</td><td>None</td><td>Renamed <code>ScopeKeysStore</code> to <code>ScopeKeys</code></td></tr><tr><td>Renamed</td><td><a href="../../../user-ref/datastore/scope-value">Scope Values</a></td><td>None</td><td>None</td><td>Renamed <code>ScopeValuesStore</code> to <code>ScopeValues</code></td></tr></tbody></table>

### Cube schema

#### Added

<table><thead><tr><th>Cube</th><th>Dimension</th><th>Hierarchy</th><th>Levels</th><th>Datastore fields</th><th>Details</th></tr></thead><tbody><tr><td>Limits</td><td>Limit</td><td>Scope (Full)</td><td>Scope (Full)</td><td>N/A</td><td>The full string representation of the <a href="../../../dev/scopes">scopes</a> present in the cube, which will include dimension and hierarchy information.</td></tr></tbody></table>

### Measures

#### Removed

<table><thead><tr><th>Cube</th><th>Measure</th><th>Details</th></tr></thead><tbody><tr><td>Limits</td><td>Scope</td><td>This scope measure has been replaced with the <code>Scope</code> level.</td></tr></tbody></table>

### 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.

<table><thead><tr><th>Old signature</th><th>New signature</th></tr></thead><tbody><tr><td><code>AHistoryRecordDTO initiate(LimitsProcessInstanceDTO object, String comment, boolean refreshKpis)</code></td><td><code>AHistoryRecordDTO initiate(LimitsProcessInstanceDTO instanceObject, String comment, boolean publishTuples, boolean refreshKpis)</code></td></tr></tbody></table>

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.