Customization Guide

Customize Kafka Listeners

The kafka listeners of module fscd-adapter-kafka rely on various interfaces. By replacing their implementation using Spring IoC the listeners can be customized.

Execution Flow

A Kafka message (TxoEvent) is received by a TxoEventListener (annotated with @KafkaListener). It uses a BusinessObjectReader to transform the raw event into a business-object specific DTO (data transfer object), which is the structured data representation needed for processing. This DTO is then passed to the BusinessObjectProcessor, which orchestrates the next steps.

Within the processor, the action is determined — for example, whether to process the insurance object or only the postings. Next, the processor uses mappers to transform the DTO into the data models required for FS-CD: an InsuranceObject and a list of Postings. Finally, these mapped objects are handed over to the FS-CD services: FscdInsuranceObjectService and FscdPostingService, which handle the transfer to FS-CD.

The flow is shown below as a sequence diagram.

kafka listener sequence

Components

The diagram below shows the interfaces and classes and their relationships using the example of the reserve change listener. It is divided into packages:

  • event - contains the TxoEvent (module f10-commons-txoutbox-event).

  • shared - contains reusable concepts across listeners.

  • reservechange - contains implementations specific to processing reserve change events.

reserve change kafka listener

  • TxoEvent: Represents the event.

  • TxoEventListener: Marker interface for the listener processing an event. The default implementation ReserveChangeEventListenerImpl for reserve changes is a @KafkaListener that uses BusinessObjectReader and BusinessObjectProcessor.

  • BusinessObjectReader: Defines the contract for reading a DTO for a TxoEvent. The default implementation ReserveChangeReader reads a ReserveChangeInformationDto from ICS.

  • BusinessObjectProcessor: Defines the contract for processing a DTO. The default implementation BusinessObjectProcessorImpl uses ActionDetermination, InsuranceObjectMapper, PostingsMapper, FscdInsuranceObjectService and FscdPostingsService.

  • ActionDetermination: Determines the action for a DTO:

    • IGNORE: Ignore the DTO.

    • CREATE: Create an insurance object and transfer postings.

    • UPDATE: Update an existing insurance object and transfer postings.

    • POSTINGS_ONLY: Transfer postings without creating or updating the insurance object.

  • InsuranceObjectMapper: Maps the DTO to an InsuranceObject. Its implementation InsuranceObjectMapperImpl uses an InsuranceObjectMapperStrategy and InsuranceObjectMapperCustomizerInsuranceObjectMapperCustomizer.

  • InsuranceObjectMapperStrategy: Defines the behavior of an InsuranceObjectMapperImpl. Usually, strategies do not need to be replaced in projects. Its abstract implementation AbstractInsuranceObjectMapperStrategy employs the Template Method pattern. It provides abstract methods for mapping attributes, which must be implemented in subclasses. The implementation for reserve changes is ReserveChangeInsuranceObjectMapperStrategy.

  • InsuranceObjectMapperCustomizer: Used by InsuranceObjectMapperImpl to customize mappings. Projects usually create their own customizer to map fields specific to the project.

  • PostingsMapper: Maps the DTO to a list of Postings. There is no shared base implementation for this mapper.

  • PostingsMapperCustomizer: Used by PostingsMapper implementations to customize mappings. Projects usually create their own customizer to map fields specific to the project.

  • FscdInsuranceObjectService: Responsible for creating or updating the InsuranceObject in FS-CD.

  • FscdPostingsService: Responsible for transferring Postings to FS-CD.

Configuration Properties

The reserve change integration is configurable via property fscd-adapter.reserve-change and can be enabled via property fscd-adapter.reserve-change.listener.enabled. For details please see the classes ReserveChangeProperties, ReserveChangeMappingProperties, ReserveChangeEventListenerImpl or the Spring configuration metadata.

AutoConfiguration

The reserve change integration is set up by the auto-configuration: ReserveChangeEventListenerAutoConfiguration.

Policy Editing Listener

The policy editing listener follows the same pattern as the reserve change listener, see package de.faktorzehn.fscdadapter.kafka.policyediting.

The policy editing integration is configurable via property fscd-adapter.policy-editing and can be enabled via property fscd-adapter.editing-finished.listener.enabled. For details please see the classes PolicyEditingProperties, PolicyEditingMappingProperties, PolicyEditingEventListenerImpl or the spring configuration metadata.

The policy editing integration is set up by the auto-configuration: PolicyEditingEventListenerAutoConfiguration.

Customization

Replace a Listener

The components for each listener and the listener itself can be replaced individually by custom implementations.

@Configuration
public class MyPolicyEditingEventListenerConfiguration {

    @Bean
    public TxoEventListener<PolicyEditingDto> myPolicyEditingEventListener(){
        return MyPolicyEditingEventListenerImpl();
    }
}
Exclude a Listener

Every listener can be deactivated individually by property:

fscd-adapter:
  policy-editing:
    listener:
      enabled = false
No Data on Update of Insurance Object

On update of an insurance object, certain fields are to be provided as "/" to indicate the field is not to be updated. The fields are configurable via property fscd-adapter.insurance-object-mapper.no-data-on-update for the function module FSCD_INSOBJECT_MAINTAIN or compatible custom replacement. See class InsuranceObjectMapperProperties for the default values.