Evaluating Limits

The IEvaluationSchedulingService and IEvaluationService

The IEvaluationSchedulingService orchestrates the scheduled evaluation of INTRADAY limit structures. The default implementation is DefaultEvaluationSchedulingService, which automatically schedules all INTRADAY structures at startup and supports runtime scheduling control via REST.

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 for more information.

When a breach or warning is detected, the Incidents 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.

Optionally, you can also store passes, which are limit evaluations that do not result in a breach or warning. See the Limit Status screen for more information.

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

Scheduled evaluations

DefaultEvaluationSchedulingService automatically schedules all INTRADAY limit structures for periodic evaluation at startup. Each scheduled evaluation re-fetches the structure from the datastore to avoid operating on stale data.

You can also schedule or unschedule individual structures at runtime using the scheduling REST endpoints.

When an INTRADAY limit is approved through a workflow, the corresponding structure is automatically scheduled if it is not already scheduled.

Properties

TaskScheduler

An IEvaluationTaskScheduler bean (which extends Spring’s TaskScheduler) is configured automatically by LimitsEvaluationServicesAutoConfiguration using the limits.evaluation.scheduler.thread-pool-size property. The thread name prefix is LimitsScheduledEvaluation-.

To use a custom scheduler, declare your own IEvaluationTaskScheduler bean — the auto-configured default will be skipped.

The IEvaluationSchedulingService maintains a map of scheduled structures, allowing you to check, add, and remove schedules both programmatically and via the REST endpoints below.

Scheduling REST endpoints

The following REST endpoints allow runtime management of scheduled evaluations. All endpoints are prefixed with /limits/rest/v2/evaluation/scheduling.

Schedule structures

• Endpoint: /limits/rest/v2/evaluation/scheduling/schedule
• Method: POST
• Example Endpoint: http://localhost:3090/limits/rest/v2/evaluation/scheduling/schedule
• Example Request Body:

{
  "structureIds": ["12345678", "-87654321"],
  "cronExpression": "0 */10 * * * *"
}

The cronExpression field is optional. If omitted, the configured default (limits.evaluation.scheduler.cron-expression) is used.

• Example Response (the resulting schedules for the requested structures):

[
  {"structureId": "12345678",  "cronExpression": "0 */10 * * * *"},
  {"structureId": "-87654321", "cronExpression": "0 */10 * * * *"}
]

Unschedule structures

• Endpoint: /limits/rest/v2/evaluation/scheduling/schedule
• Method: DELETE
• Example Endpoint: http://localhost:3090/limits/rest/v2/evaluation/scheduling/schedule
• Example Request Body:

["12345678", "-87654321"]

• Example Response (map of structure ID to true if cancelled, false if not found):

{
  "12345678":  true,
  "-87654321": false
}

List all active schedules

• Endpoint: /limits/rest/v2/evaluation/scheduling/schedules
• Method: GET
• Example Endpoint: http://localhost:3090/limits/rest/v2/evaluation/scheduling/schedules
• Example Response:

[
  {"structureId": "12345678", "cronExpression": "0 */5 * * * *"}
]

On-demand limit evaluation

On-demand evaluation is driven by IEvaluationService. In general this is done through the UI by evaluating limits, but could also be done programmatically or via REST requests.

When evaluating limits on-demand, DefaultEvaluationService creates two TaskExecutors. 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:

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

REST

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

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

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

[
  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):

[
  12345678,
  -87654321
]

Evaluate by KPI

This is equivalent to evaluation per limit structure. 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:

{
    "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

Unschedule tasks (deprecated)