Customization Guide

Customize Kafka Listeners

The kafka listeners rely on various interfaces of modules fscd-adapter-kafka and fscd-adapter-business. 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 ReserveChangeEventListener for reserve changes is a @KafkaListener that uses BusinessObjectReader and BusinessObjectProcessor.

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

  • Processor: Defines the contract for processing a DTO.

  • InsuranceObjectMapper: Maps the DTO to an InsuranceObject.

  • PostingsMapper: Maps the DTO to a list of Postings.

  • 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, ReserveChangeEventListener or the Spring configuration metadata.

AutoConfiguration

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

Claim Payment Listener

The claim payment listener follows the same pattern as the reserve change listener, see package de.faktorzehn.fscdadapter.kafka.claimpayment.

The claim payment integration is configurable via property fscd-adapter.claim-payment and can be enabled via property fscd-adapter.claim-payment.listener.enabled. For details please see the classes ClaimPaymentProperties, ClaimPaymentMappingProperties, ClaimPaymentEventListener or the Spring configuration metadata.

The claim payment integration is set up by the auto-configuration: ClaimPaymentEventListenerAutoConfiguration.

Failed Claim Payment Listener

The failed claim payment listener follows the same pattern as the claim payment listener, see package de.faktorzehn.fscdadapter.kafka.failedpayment.

The integration can be enabled via property fscd-adapter.failed-payment.listener.enabled. It reuses the mapping configuration from the claim payment integration and therefore requires the claim payment integration to be enabled as well.

The claim payment integration is set up by the auto-configuration: FailedPaymentEventListenerAutoConfiguration.

Receivable Listener

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

The receivable integration is configurable via property fscd-adapter.receivable and can be enabled via property fscd-adapter.receivable.listener.enabled. For details please see the classes ReceivableProperties, ReceivableMappingProperties, ReceivableEventListener or the Spring configuration metadata.

The receivable integration is set up by the auto-configuration: ReceivableEventListenerAutoConfiguration.

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 VbPolicyEditingProperties, VbPolicyEditingMappingProperties, PolicyEditingEventListenerImpl or the spring configuration metadata.

The policy editing integration is set up by the auto-configuration: PolicyEditingEventListenerAutoConfiguration, VbPolicyEditingEventListenerConfiguration and VbPolicyEditingEventListenerAutoConfiguration.

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

Company Code Mapping

All Kafka listeners use a shared, centralized configuration for mapping company codes to FS-CD. Company codes are mapped based on the company ID from the origin system (IPM or ICS).

The mapping is configured via properties under fscd-adapter.companies[*]:

fscd-adapter:
  companies:
    - company-id: "F"
      company-code-general-ledger: FSCD
      company-code-sub-ledger: FSCD
Configuration Properties

  • fscd-adapter.companies[*].company-code-general-ledger: Map of company ID to company code for general ledger (required). The company ID serves as the key, and the corresponding FS-CD company code as the value.

  • fscd-adapter.companies[*].company-code-sub-ledger: Map of company ID to company code for sub ledger (optional). If no mapping is configured for a specific company ID, the general ledger mapping will be used as a fallback.

Implementation Details

Each listener’s PostingsMapper uses the shared CompanyCodeMappingProperties to map company codes when creating postings for FS-CD.

For details see the class CompanyCodeMappingProperties and the respective PostingsMapper implementations.