☰
Navigation :

The Atoti Adjustments Services API standalone module

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, with a “main” flag to set an input field as a main field. This flag is used by the UI to render the input field in the correct place 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.
  • 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.

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 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 and a value.
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.

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:

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.

Adding adjustment support to an application server

Importing the library

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

<dependency>
    <groupId>com.activeviam.apps</groupId>
    <artifactId>adjustments-services</artifactId>
    <version>4.0.1</version>
</dependency>

Adding services to the application configuration

Adjustments

Spring configuration

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

@Import(value = {
        SupportedAdjustmentsService.class,
        AdjustmentStatusService.class,
        AdjustmentExecutionService.class,
        AdjustmentRestService.class
})

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.

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

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.

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:

@Import(value = {
        SupportedBranchAwareAdjustmentsService.class,
        SupportedBranchAwareAdjustmentsRestService.class,
})

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

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