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

# Atoti Limits Java integration

> “How to connect an Atoti Server instance to a running Atoti Limits server using the Java auto-configuration module, including the compatibility matrix, setup steps, and troubleshooting guidance”

## Overview

The Atoti Limits Java auto-configuration module connects an Atoti Server instance (the “Connected Server”) to a running Atoti Limits server. It uses [Spring Auto-configuration](https://docs.spring.io/spring-boot/reference/using/auto-configuration.) to bootstrap the required services and send a connection request to Atoti Limits.

This module enables Atoti Limits to manage limits on data served by Atoti Server. Once connected, Atoti Limits can evaluate limits against the measures and hierarchies exposed by the Connected Server.

<Note>
  Atoti Limits does not require the connected server to be an ActiveViam Business Solution, it
  can be any instance of Atoti Server.
</Note>

The auto-configuration resides in the `limits-auto-config-*` modules. These modules are responsible for bootstrapping the Connected Server with any services required by Atoti Limits and for sending a connection request to Atoti Limits with required information.

## Compatibility matrix

This table lists the versions of Atoti Server compatible with each Atoti Limits
version. If you are using a solution, please check the
underlying version of Atoti Server to see if your version of the solution is compatible.

<table><thead><tr><th>Atoti Limits version</th><th>Atoti Server version</th></tr></thead><tbody><tr><td>4.2</td><td>6.0.x, 6.0.x-sb3, 6.1.x</td></tr><tr><td>4.1</td><td>6.0.x, 6.0.x-sb3, 6.1.x</td></tr><tr><td>4.0</td><td>6.0.x, 6.0.x-sb3, 6.1.x</td></tr><tr><td>3.3</td><td>5.11.x, 6.0.x, 6.0.x-sb3</td></tr><tr><td>3.2</td><td>5.9.x, 5.10.x, 5.11.x, 6.0.x, 6.0.x-sb3</td></tr></tbody></table>

## Prerequisites

1. The Atoti server(s) you wish to connect to must contain a slicing date hierarchy. This hierarchy
   will be used by Atoti Limits when evaluating limits.
2. User and role configurations must be consistent between Atoti Limits and the connected
   Atoti server(s) in order to guarantee proper access control. We recommend placing your security
   configurations in a single module and referencing that module in both Atoti Limits and the
   Atoti server.

## How does the connection process work?

From a high-level view, the connection process works as follows:

1. Once Atoti Limits starts, it sits idle until it receives a connection request from the
   Connected Server.
2. When the Connected Server starts, it pings Atoti Limits to check if it is available to
   receive a connection request.
3. After both Atoti Limits and the Connected Server are started, the Connected Server will
   start some services and gather information to send a connection request to Atoti Limits.

<Note>
  The order in which the servers are started is irrelevant.
</Note>

4. The connection request contains information about the Connected Server that Atoti Limits
   requires to connect.
5. Atoti Limits connects to the Connected Server and is now ready to manage limits.
6. During the lifetime of the application, Atoti Limits will manage all of the Connected
   Servers that it is connected to.

## How to integrate a Connected Server with Atoti Limits

Follow these steps to integrate a Connected Server with Atoti Limits.

### Step 1: Import the auto-configuration dependency in the Connected Server

The `limits-auto-config-*` Maven dependency must be added to the Connected Server project. The correct artifact depends on the version of Atoti Server in use.

Add the following dependency to the project `pom.xml` file:

```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<dependency>
  <groupId>com.activeviam.modules.limits</groupId>
  <artifactId>limits-auto-config-{VERSION}</artifactId>
  <version>{ATOTI-LIMITS-MODULE-VERSION}</version>
</dependency>
```

The following table lists each artifact and its compatible Java versions:

<table><thead><tr><th>Atoti Server version</th><th>Auto-config artifact</th><th>Compatible Java versions</th></tr></thead><tbody><tr><td>6.0.X</td><td>limits-auto-config-60</td><td>11, 17</td></tr><tr><td>6.0.X-sb3</td><td>limits-auto-config-60-sb3</td><td>17</td></tr><tr><td>6.1.X</td><td>limits-auto-config-61</td><td>21</td></tr></tbody></table>

### Step 2: Configure the auto-configuration properties in the Connected Server

The auto-configuration module requires a set of properties to establish the connection. Configure these properties in the `application.yml` file on the **Connected Server**.

The full list of properties is available in the [Auto-configuration properties section](../../user-ref/properties/config-properties/limits-integration-common).

<Note>
  Not all properties are required, but they are all listed in the event that your Connected Server is
  unable to derive the properties automatically.
</Note>

### Step 3: Configure the inter-server-event-service properties in Atoti Limits

The Atoti Limits server needs to know where to find the Connected Server. Set the following configuration properties in the `application.yml` file on the **Atoti Limits server**.

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
activeviam:
  apps:
    inter-server-event-service:
      issuer:
        target-servers:
          - name: <Connected Server>
            url: <Connected Server URL>
```

where:

* `<Connected Server>` is the name of the Connected Server and should be the same as the value (defined or auto-configured) of `limits.autoconfiguration.server-name` in the connected server.
* `<Connected Server URL>` is the URL of the Connected Server and should be the same as the value (defined or auto-configured) of `limits.autoconfiguration.atoti-base-url` in the connected server.

### Step 4: Start the servers

The order in which the servers start does not matter.

#### Start the Limits server

Start the Limits server using the [installation instructions](../getting-started#installing-the-starter-project).
Limits will wait for a connection from the Atoti Server.

#### Start the Connected Server

Start the Connected Server as normal. This should trigger a connection request.

## Troubleshooting

If the connection is unsuccessful, enable `debug` logging for further investigation.

<Note>
  Ensure that within the ActivePivotConfig of your connected solution, the contextValueManager
  method is not setting the ActivePivotContentService to null.

  If the ActivePivotContentService is
  null, KPIs will not appear in the UI, even if they are present in the content server.

  Sometimes this can be fixed by setting the property `contentServer.context-values.ignore`
  to `false`.
</Note>