The Sign-off API standalone module

The Sign-off API standalone module

With the introduction of adjustment capabilities to the Sign-Off Module, and the need for any application server to easily integrate these capabilities, this standalone library was created in order to provide interfaces, service implementations and DTOs.

Interfaces and implementations

Sign-off workflow

Interfaces and implementations of services handling sign-off workflow endpoints.

ISignOffService interface

An interface covering:

• Task initiation
• Task approval
• Export execution
• Export status retrieval
• KPI retrieval for specific sign-off instances

ISignOffRestService interface

A REST service interface wrapping the ISignOffService methods in REST endpoints.

DTOs

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 autowires a collection of SupportedAdjustmentDTO beans instantiated by the application.

The service rejects any adjustment with a duplicate key.

DTOs

Adjustment execution

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

IAdjustmentExecutionService interface

An interface providing:

• An adjustment execution endpoint which returns an execution ID for use with the status service.
• An adjustment deletion endpoint returning 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 that is 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

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

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)
• Adjustment deletion (see AdjustmentExecutionService)
• Status retrieval (see AdjustmentStatusService)
• Supported adjustments retrieval (including by measure - see SupportedAdjustmentsService)
• Rejected adjustments retrieval (see SupportedAdjustmentsService)

Helpers

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

Adding adjustment support to an application server

Importing the library

To use the Sign-off API library, import it in the Maven POM file:

<dependency>
    <groupId>com.activeviam.tools</groupId>
    <artifactId>signoff-ext</artifactId>
    <version>1.5.0</version>
</dependency>

Adding services to the application configuration

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.

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, BiConsumer<AdjustmentRequestDTO, String>>.

The map keys must match the SupportedAdjustmentService supported adjustments. The BiConsumer objects 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.