Navigation :

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

DTO	Description
SignOffProcessKey	Task key object, containing a process definition name and an as-of date.
SignOffProcessInstanceExportDTO	Export request object, containing information required for data export.
SignOffExportStatusDTO	Information object containing the result of an export execution.
KpiDTO	Data object for the goal, value and status of a KPI.

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

DTO	Description
TypedFieldDTO	Data object containing a field name and a type.
LevelTypedFieldDTO	Extension of the `TypedFieldDTO` object, with an added `levelPath` property.
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 `TypedFieldDTO`)

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

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:

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:

Class	Description
ReponseDTO	A DTO containing status and data fields.
KeyGenerator	A helper object for generating a definition key based on a name and an as-of date.

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

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