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

# Evaluate limits

> How Atoti Limits orchestrates limit evaluation using IEvaluationTaskManager and IEvaluationService, including Intraday scheduled evaluations, TaskScheduler configuration, and on-demand REST endpoints at limit, structure, and application levels

## The `IEvaluationTaskManager` and `IEvaluationService`

The `IEvaluationTaskManager` orchestrates the evaluation of limits. The default implementation of this interface can be found in `DefaultEvaluationTaskManager`.
The `IEvaluationService` contains the logic for evaluating limits. The default implementation of this interface can be found in `DefaultEvaluationService`. For
both of these interfaces, you can define your own implementation - see [Adding Custom Evaluation Logic](./dev-extensions/custom-evaluation) for more information.

When a breach or warning is detected, the [Incidents Store](../user-ref/datastore/incident-store) is populated, the incident workflow is updated, and an `incident*.csv` file is generated. For details on the `incident*.csv` file, see [Incidents file](./evaluation-tasks/incidents).

Optionally, you can also store passes, which are limit evaluations that do not result in a breach or warning. See the
[Limit Status screen](../user-ref/manage-incidents/status-screen#include-all-limit-evaluations) for more information.

Limit evaluations through the `IEvaluationService` can either be scheduled or executed on-demand.

## Scheduled evaluations

The `IEvaluationTaskManager` automatically schedules future evaluations for limit structures with an Intraday polling frequency.
You can configure the Intraday polling frequency using the `limits.alert-task.sample-rate-cron` property values.

### Properties

<table><thead><tr><th>Property</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>limits.task-scheduler.thread-pool-size</td><td>4</td><td>Thread pool size for the task scheduler.</td></tr><tr><td>limits.alert-task.sample-rate-cron</td><td>0 \*/5 \* \* \* \*</td><td>Cron expression for the Intraday Alert task’s cron job.</td></tr></tbody></table>

### TaskScheduler

The [TaskScheduler](https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-task-scheduler) Bean allows you to schedule alert tasks,
specified by the class `AAlertTask`, and can be found in the `ThreadPoolTaskSchedulerConfig.java` class. The quantity of threads allotted to the `TaskScheduler` can
be configured with the `limits.task-scheduler.thread-pool-size` property value. The default value is 4 threads.

The `IEvaluationTaskManager` maintains a map of alert tasks, which
are keyed by a unique task key. When alert tasks are scheduled, they are added to the map. This allows you to unschedule tasks if needed.

## On-demand limit evaluation

The `IEvaluationTaskManager` is also responsible for evaluating limits on-demand. In general this is done through the UI by [evaluating limits](../user-ref/manage-incidents/evaluate-limits),
but could also be done programmatically or via REST requests.

When evaluating limits on-demand, `DefaultEvaluationService` creates two
[`TaskExecutors`](https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-task-executor). One executor is responsible for
running the evaluation code relevant to the limit structures and the other deals with the code pertaining to the limits. We use two executors to improve the speed of evaluation.

You can configure the executors to use an arbitrary number of threads using the following [Configuration Property](../user-ref/properties/config-properties/limits-activeviam):

<table><thead><tr><th>Property</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>limits.incident.evaluation.parallel-tasks</td><td>-1</td><td>Thread pool size for the evaluation task executors. A negative value indicates that half the available processors will be used.</td></tr></tbody></table>

You can also configure the behavior when errors occur. For example, you can include a stack trace in the response by using the following property from the [application.yml](../user-ref/properties/property-files/application-yml#section-incidents) file:

<table><thead><tr><th>Property</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>limits.incident.evaluation.error.include-stacktrace</td><td>false</td><td><code>true</code> if the stack trace should be available in the evaluation response to the UI.</td></tr></tbody></table>

### REST

Evaluation REST endpoints are available for:

* [On-demand limit evaluation](#on-demand-limit-evaluation)
* [Unscheduling tasks from the TaskScheduler](#unschedule-tasks-from-the-taskscheduler)

For any of the following endpoints that use an `asOfDate` query parameter, note that the `asOfDate` is optional. It is included in the examples to demonstrate the syntax, but if not provided, Atoti Limits defaults to the date
provided in the [as\_of\_date.csv file](../user-ref/input-files/as_of_date). The result of each response is a DTO containing the number of breaches, warnings and passes (if enabled) as well as any errors encountered during evaluation.

<Note>
  Triggering an evaluation populates the [incidents store](../user-ref/datastore/incident-store) and creates or updates the workflow of the resulting incident.
</Note>

#### At the limit level

For evaluation on a per-limit basis, the following two REST endpoints can be used:

##### Evaluate a single limit

* Endpoint: `/limits/rest/v2/limitEvaluation/limit/evaluate/{limitId}`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/limit/evaluate/12345678?asOfDate=2023-01-31`

##### Evaluate multiple limits

<Note>
  The limit keys provided do not need to belong to the same limit structure.
</Note>

* Endpoint: `/limits/rest/v2/limitEvaluation/limit/evaluate`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/limit/evaluate?asOfDate=2023-01-31`
* Example Request Body (the limit keys):

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
[
  12345678,
  -87654321
]
```

#### At the limit structure level

To evaluate on a per-limit structure basis, the following two REST endpoints can be used:

##### Evaluate a single limit structure

* Endpoint: `/limits/rest/v2/limitEvaluation/structure/evaluate/{limitStructureId}`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/structure/evaluate/12345678?asOfDate=2023-01-31`

##### Evaluate multiple limit structures

* Endpoint: `/limits/rest/v2/limitEvaluation/structure/evaluate`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/structure/evaluate?asOfDate=2023-01-31`
* Example Request Body (the limit structure keys):

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
[
  12345678,
  -87654321
]
```

##### Evaluate by KPI

This is equivalent to [evaluation per limit structure](#at-the-limit-structure-level). To evaluate a KPI against the business cubes, use the following REST endpoint:

* Endpoint: `/limits/rest/v2/limitEvaluation`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/evaluate`
* Example Request Body:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
    "kpiName":"SA Book Limit",
    "cubeName":"StandardisedApproachCube",
    "serverName":"FRTB"
}
```

#### At the application level

This endpoint evaluates all approved limits:

* Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/evaluate/all`
* Method: Post
* Example Endpoint: `http://localhost:3090/limits/rest/v2/limitEvaluation/evaluate/all`

<Note>
  This endpoint is not optimized and may not be performant.
</Note>

### Unschedule tasks from the TaskScheduler

To unschedule a task from the `IEvaluationTaskManager`, use the following REST endpoint:

* Endpoint: `/limits/rest/v2/limitEvaluation/unschedule`
* Method: POST
* Example Endpoint: `http://localhost:3090/limits/v2/rest/limitEvaluation/unschedule`

Example Body:

```JSON theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
   "serverName":"FRTB",
   "cubeName":"StandardisedApproachCube",
   "kpiName":"SA Book Limit",
   "pollingFrequency":"INTRADAY"
}
```

Example Response (`true` if the task is unscheduled successfully, `false` otherwise):

```JSON theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "true"
}
```