> ## 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 Adjustments Services API

> Reference for the Atoti Adjustments Services API library, covering interfaces and implementations for adjustment support, execution, status tracking, branch-aware operations, and REST services.

This standalone library was created to provide interfaces, service implementations, and DTOs for adjustments and
what-if operation executions. The objective is to offer an easier integration of these capabilities in any application server.

## Interfaces and implementations

### Adjustment support

Interfaces and implementations that allow an application server to publish the list of supported adjustment types and required inputs for adjustment execution.

#### ISupportedAdjustmentsService

An interface allowing retrieval of:

* The full set of supported adjustments
* Supported adjustments for a given measure name
* A specific adjustment, by key
* A set of rejected adjustment types

#### SupportedAdjustmentsService

An implementation of the `ISupportedAdjustmentService` interface, which auto-wires a collection of `SupportedAdjustmentDTO` beans instantiated by the application.

The service rejects any adjustment with a duplicate key.

#### DTOs

| DTO                    | Description                                                                                                                                                                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TypedFieldDTO          | Data object containing a field name, a type, a level path, and an optionality flag.                                                                                                                                                                      |
| InputTypedFieldDTO     | Extension of the `TypedFieldDTO` object to include a “label” and a “main” flag. These properties are used by the UI to display the label for the input field and position the input field correctly in the adjustments window.                           |
| SupportedAdjustmentDTO | Data object for the definition of supported adjustments. Holds information about: - The stores the adjustment applies to - Required filters (as a set of `LevelTypedFieldDTO`) - Supported measures - Required inputs (as a set of `InputTypedFieldDTO`) |

### Adjustment execution

Interfaces and implementations to allow wiring adjustment executions within an application server.

#### IAdjustmentExecutionService interface

An interface providing:

* An adjustment execution endpoint that returns an execution ID for use with the status service.
* A bulk adjustment execution endpoint that returns a list of execution IDs per request for use with the status service.
* An adjustment deletion endpoint that returns an execution ID for use with the status service.
* Direct access to the `ExecutorService` object.

#### AdjustmentExecutionTask

Runnable execution object holding the request, the execution ID and the executor method used by the service.

#### AdjustmentBulkExecutionTask

Runnable execution object holding the requests, the execution IDs per request and the executor method used by the service.

#### AdjustmentDeletionTask

Runnable execution object holding the deletion request, the execution ID and the executor deletion method used by the service.

#### AdjustmentExecutionService

An implementation of the `IAdjustmentExecutionService` interface with methods for creating the following:

* An `AdjustmentExecutionTask`, validating the request input, wiring application-defined executors and submitting the
  resulting task to the `ExecutorService`.
* An `AdjustmentBulkExecutionTask`, validating each request input, wiring application-defined executors and submitting the
  resulting task to the `ExecutorService`.
* An `AdjustmentDeletionTask`, wiring application-defined executors and submitting the
  resulting task to the `ExecutorService`.

The request validation checks for the existence of a supported adjustment with the given key, matches the input measures to the supported measures for the retrieved adjustment and checks request filters and input against the `SupportedAdjustmentDTO` of the adjustment type.

#### DTOs

| DTO                             | Description                                                                                                                                                                                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NamedValueDTO                   | Data object containing a name, a value and a memberPath.                                                                                                                                                                                                                                                                  |
| AdjustmentRequestDTO            | Request object defining: - The server name to which the execution request is sent - The key of the adjustment type - The user and task for which the adjustment is requested - A set of `NamedValueDTO` filters - A set of measures for which the adjustment applies and the required input (as a set of `NamedValueDTO`) |
| AdjustmentDeletionRequestDTO    | Request object defining: - The user and task for which the deletion is requested - A set of `execution IDs` that are to be deleted.                                                                                                                                                                                       |
| ExecutionIdAdjustmentRequestDTO | Response object containing: - The execution ID of an exectution request - The exectution request object                                                                                                                                                                                                                   |

### Execution status

Interfaces and implementations that publish the status of a given adjustment request.

#### IAdjustmentStatusService interface

An interface containing endpoints for:

* Creating an adjustment execution task
* Retrieving the source tag for a given execution task
* Retrieving the status of an execution task
* Updating the status of an execution task

#### AdjustmentStatusService

An implementation of the `IAdjustmentStatusService` interface, holding the status of executions in a `ConcurrentHashMap` wrapped in a `ReentrantLock`.

#### DTOs

| DTO                | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| ExecutionStatusDTO | A status object holding the status of an execution task and the source tag for that execution. |

#### The status enum

The Status `Enum` provides a set of possible statuses for an execution:

* Requested
* Pending
* Executed
* Failed
* Cancelled
* Deleting
* Deleted

### REST services

All adjustment services are also wrapped in a REST service for interoperability.

#### IAdjustmentRestService interface

Interface providing REST endpoints for:

* Adjustment execution (see [AdjustmentExecutionService](#adjustmentexecutionservice))
* Bulk adjustment execution (see [AdjustmentExecutionService](#adjustmentexecutionservice))
* Adjustment deletion (see [AdjustmentExecutionService](#adjustmentexecutionservice))
* Status retrieval (see [AdjustmentStatusService](#adjustmentstatusservice))
* Supported adjustments retrieval (including by measure - see [SupportedAdjustmentsService](#supportedadjustmentsservice))
* Rejected adjustments retrieval (see [SupportedAdjustmentsService](#supportedadjustmentsservice))

### Helpers

The following classes are provided as helper objects for any services that might require them:

| Class        | Description                                                                        |
| ------------ | ---------------------------------------------------------------------------------- |
| KeyGenerator | A helper object for generating a definition key based on a name and an as-of date. |

### Branch-aware adjustment (what-if) support

Interfaces and implementations that allow an application server to publish the list of supported branch-aware adjustment types and required inputs for
branch-aware adjustments execution.

#### ISupportedBranchAwareAdjustmentService

An interface to retrieve:

* The full set of supported branch-aware adjustments
* A specific branch-aware adjustment by key
* A set of rejected branch-aware adjustment types

#### SupportedBranchAwareAdjustmentsService

An implementation of the `ISupportedBranchAwareAdjustmentService` interface, which autowires a collection of `SupportedBranchAwareAdjustmentDTO` beans instantiated by the application.

The service rejects any branch-aware adjustment with a duplicate key.

#### DTOs

| DTO                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SupportedBranchAwareAdjustmentDTO | Data object for the definition of supported branch-aware adjustments. Holds information about: - The stores the adjustment applies to - Required filters (as a set of `LevelTypedFieldDTO`) - Required inputs (as a set of `InputTypedFieldDTO`) - The branch in which the adjustment will be performed - The endpoint of the REST service used for the what-if operations **NOTE:** The `measures` field is currently only a placeholder for future implementation. No logic is associated to it currently. |

### REST service

The supported branch-aware adjustment service is also wrapped in a REST service for interoperability.

#### ISupportedBranchAwareAdjustmentsRestService interface

A REST service interface wrapping the `ISupportedBranchAwareAdjustmentService` methods in REST endpoints.

#### SupportedBranchAwareAdjustmentsRestService class

An implementation of the interface `ISupportedBranchAwareAdjustmentsRestService`.

## Add adjustment support to an application server

### Import the library

To use the Atoti Adjustments Services API library, import it into the Maven POM file:

```XML theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>adjustments-services</artifactId>
    <version>4.1.3</version>
</dependency>
```

### Add services to the application configuration

#### Adjustments

##### Spring configuration

The provided service implementations can be imported directly within the application configuration:

```Java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Import(value = { AdjustmentServicesCoreConfig.class })
```

Which will import:

* `AdjustmentRestService`
* the default implementation of `IAdjustmentExecutionService`, `AdjustmentExecutionService`, unless another implementation is exposed in the application
* the default implementation of `IAdjustmentStatusService`, `AdjustmentStatusService`, unless another implementation is exposed in the application
* the default implementation of `ISupportedAdjustmentsService`, `SupportedAdjustmentsService`, unless another implementation is exposed in the application

Once imported, the services will autowire any relevant beans provided in the application and expose the REST service endpoints.

##### Required application properties

The following properties are required by the services, when imported into an application.

| Property                                 | Value | Description                                               |
| ---------------------------------------- | ----- | --------------------------------------------------------- |
| sign-off.adjustments.scheduler-pool-size | 1     | Scheduler pool size for the adjustment execution service. |

#### Implement adjustments

##### Supported adjustments

Any Spring Bean of type `SupportedAdjustmentDTO` will be automatically collected and exposed through the `SupportedAdjustmentService`.

The service will check the adjustment types of the defined Beans against duplication. Any duplicated keys will be added to the set of rejected adjustments.

##### Adjustment execution

Application servers are responsible for implementing their particular adjustment types, as Spring Beans. For this purpose, the `AdjustmentExecutionService` autowires:

* a `Map<String, AdjustmentExecutor>`
* a `Map<String, BulkAdjustmentExecutor>`

The map keys must match the `SupportedAdjustmentService` supported adjustments.
`AdjustmentExecutor` functions must accept an `AdjustmentRequestDTO` together with an execution ID `String` and contain the logic for executing an adjustment. The implementation must update the `AdjustmentStatusService` as appropriate for the execution flow.
`BulkAdjustmentExecutor` functions must accept a `List<ExecutionIdAdjustmentRequestDTO>` and contain the logic for executing adjustments in bulk. The implementation must update the `AdjustmentStatusService` as appropriate for the execution flow.

##### Adjustment deletion

Deletion is also the responsibility of application servers, which need to define an `AdjustmentDeleter`. This function should accept an `AdjustmentDeletionRequestDTO` and an execution ID `String` and execute the required steps to remove an adjustment from the application. As with the `AdjustmentExecutor` functions, the `AdjustmentStatusService` should be updated as appropriate.

#### Branch-aware operations

##### Spring configuration

The provided service implementations can be imported directly within the application configuration:

```Java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Import(value = {
        SupportedBranchAwareAdjustmentsService.class,
        SupportedBranchAwareAdjustmentsRestService.class,
})
```

Once imported, the services autowires any relevant beans provided in the application and exposes the REST service endpoints.

#### Implement branch-aware adjustments

##### Supported branch-aware adjustments

Any Spring Bean of type `SupportedBranchAwareAdjustmentDTO` is automatically collected and exposed through the `SupportedBranchAwareAdjustmentsService`.

The service checks the branch-aware adjustment types of the defined Beans against duplication. Any duplicated keys are added to the set of rejected branch-aware adjustments.

##### Branch-aware adjustment execution

Application servers are responsible for implementing their particular branch-aware adjustment types.
The input to each REST service used for the execution request of a branch-aware adjustment type must be an instance of `BranchAwareAdjustmentRequestDTO`.