Integration Guide

Integration Layer

Integrations with FS-CD are known to be highly project-specific demanding customizations that are best made through direct source code changes. Thus, the reference implementation of the integration layer is delivered to projects as the sources of Maven modules.

Modules

The following modules of group de.faktorzehn.fscd-adapter contain the reference implementation.

The recommended multi-module Maven project structure is outlined in chapter Project Setup.
fscd-adapter-sample-ics

Processes claim-related events.

Supported events published by ICS:

  • reserve-changed: transfers a change in reserve to FS-CD

  • payment-transferred: transfers a payment to FS-CD

  • payment-failed: reverses postings for a failed payment in FS-CD

  • receivable-transferred: transfers a receivable to FS-CD

Supported events published by FS-CD:

  • payment-returned: notifies ICS that a payment could not be made, e.g., due to invalid account details

The end-to-end flow for a failed payments involves three events in the following order: payment-transferred → payment-returned → payment-failed.

The module contains separate packages e.g., receivable, claimpayment etc. for different claim-related processes.

fscd-adapter-sample-ipm-base

Processes policy-related events published by IPM systems that rely on the international Insurance Base (IB).

Supported events published by IPM:

  • editing-finished: transfers postings for a policy editing.

  • version-becoming-effective: indicates policy effectiveness, used for policyholder changes.

fscd-adapter-sample-ipm-basis

Processes policy-related events published by IPM systems that rely on the German Versicherungsbasis (VB).

Supported events published by IPM:

  • editing-finished: transfers postings for a policy editing.

  • version-becoming-effective: indicates policy effectiveness, used for policyholder changes.

fscd-adapter-sample-shared

Shared foundation providing base classes, interfaces, and common utilities for event processing.

fscd-adapter-sample-webapp

Bundles and configures the integration layer, REST API and web application into a single runnable Spring Boot application.

Execution Flow

The following diagram depicts the Java components participating in steps 5 to 9 of the event-driven integration pattern outlined in chapter Event-Driven Integration, along with their interactions.

This flow applies to all listeners that create InsuranceObjects and Postings in FS-CD for events within the Faktor Zehn Suite.

kafka listener sequence
Figure 1. simplified execution flow

The main differences between listeners are the event-specific business objects and mapping logic.

The assignment of Insurance Object Reference Number (VTREF), Posting Position Number (POSNR) and Business Process Number (GSFNR) can be customized in the *InsuranceObjectMapper and *PostingMapper respectively.

Implementation Details

The implementation uses Spring for Apache Kafka's @KafkaListener and non-blocking retries.

Component Registration

All components of the integration layer are registered as Spring beans using the @Component annotation. Thus, the listeners are automatically enabled when the corresponding module is included as a dependency of the fscd-adapter-webapp module and its packages are discovered during Spring Boot component scanning.

Configuration Properties

The listeners use Spring @ConfigurationProperties to configure, for example, mappings between the Faktor Zehn and FS-CD domains. These properties classes are registered using @EnableConfigurationProperties on listener-specific @Configuration classes.

@Configuration
@EnableConfigurationProperties(ReceivableMappingProperties.class)
public class ReceivableConfiguration {
}

The following table provides an overview of all listeners and their configuration:

Listener Event Topic Configuration Properties Class Property Prefix REST Endpoints Module

ReserveChangeEventListener

de.faktorzehn.ics.event.reserve-changed

ReserveChangeMappingProperties

fscd-adapter.reserve-change

GET /{claimNo}/reserve-changes/{reserveChangeNo}

fscd-adapter-sample-ics

ClaimPaymentEventListener

de.faktorzehn.ics.event.payment-transferred

ClaimPaymentMappingProperties

fscd-adapter.claim-payment

GET /{claimNo}/payments/{claimPaymentNo}

fscd-adapter-sample-ics

FailedPaymentEventListener

de.faktorzehn.ics.event.payment-failed

ClaimPaymentMappingProperties (shared with ClaimPaymentEventListener)

fscd-adapter.failed-payment

GET /{claimNo}/payments/{claimPaymentNo}

fscd-adapter-sample-ics

ReceivableEventListener

de.faktorzehn.ics.event.receivable-transferred

ReceivableMappingProperties

fscd-adapter.receivable

GET /{claimNo}/receivables/{receivableNo}

fscd-adapter-sample-ics

PaymentReturnedEventListener

de.faktorzehn.fscd.payment-returned

PaymentReturnedProperties

fscd-adapter.payment-returned

POST /paymentupdate

fscd-adapter-sample-ics

IbPolicyEditingEventListener

de.faktorzehn.ipm.event.editing-finished

IbPolicyMappingProperties

fscd-adapter.policy-editing and fscd-adapter.policy

GET /policies/{policyNo}/editings/{editingNumber}
GET /policies/{policyNo}/versions?validAt=…​

fscd-adapter-sample-ipm-base

VbPolicyEditingEventListener

de.faktorzehn.ipm.event.editing-finished

VbPolicyMappingProperties

fscd-adapter.policy-editing and fscd-adapter.policy

GET /policies/{policyNo}/editings/{editingNumber}
GET /policies/{policyNo}/versions?validAt=…​

fscd-adapter-sample-ipm-basis

IbPolicyholderChangeEventListener

only processes event if payload of event contains a PHC change marker

de.faktorzehn.ipm.event.version-becoming-effective

IbPolicyMappingProperties

fscd-adapter.policyholder-change and fscd-adapter.policy

GET /policies/{policyNo}/versions?validAt=…​

fscd-adapter-sample-ipm-base

VbPolicyholderChangeEventListener

only processes event if payload of event contains a PHC change marker

de.faktorzehn.ipm.event.version-becoming-effective

VbPolicyMappingProperties

fscd-adapter.policyholder-change and fscd-adapter.policy

GET /policies/{policyNo}/versions?validAt=…​

fscd-adapter-sample-ipm-basis
Policy Version Lookup for Policy Editing Postings

The IbPolicyEditingEventListener and VbPolicyEditingEventListener group the postings of a policy editing by their due date. For each distinct due date, the policy version valid on that date is loaded via GET /policies/{policyNo}/versions?validAt={dueDate}. The insurance object and postings are then created or updated per group, using the policyholder from the respective policy version.

This ensures that postings are assigned to the correct insurance object when the policyholder changes between due dates. If the editing contains no postings, the policy version valid at the editing’s finish date is used to update the insurance object.

Payment Returned Processing

The PaymentReturnedEventListener processes payment-returned events published by FS-CD via SAP info container and notifies ICS via POST /paymentupdate.

The return reason from the FS-CD info container is mapped to an ICS payment failure type. By default, the external return reason code (RLHBK) from the info container is used directly as the payment failure type.

If a project requires a custom mapping from the internal return reason code (RLGRD) to the payment failure type, it can be configured via fscd-adapter.payment-returned.return-reasons:

fscd-adapter:
  payment-returned:
    return-reasons:
      901: AC01
      902: AC04

If this mapping is configured (non-empty), RLGRD is mapped using the configured entries. An unmapped code results in the message being forwarded to the dead-letter topic.

Topic Configuration

Each listener can consume from one or multiple Kafka topics configured via <property-prefix>.topics.

For multiple topics, provide a comma-separated list:

fscd-adapter:
  reserve-change:
    topics: de.faktorzehn.ics-shu.event.reserve-changed,de.faktorzehn.ics-kf.event.reserve-changed
Retry Configuration

The FS-CD Adapter uses Spring Kafka’s non-blocking retry mechanism to handle failed message processing without blocking the Kafka consumer. The RetryTopicConfiguration in class KafkaConfig defines the retry behavior:

@Bean
public RetryTopicConfiguration retryTopicConfiguration(KafkaTemplate<String, String> template) {
    return RetryTopicConfigurationBuilder
            .newInstance()
            .maxAttempts(5)                                    (1)
            .exponentialBackoff(60_000, 5, Integer.MAX_VALUE)  (2)
            .retryTopicSuffix("-fscd-adapter-retry")           (3)
            .retryOn(ForwardToRetryTopicException.class)       (4)
            .dltSuffix("-fscd-adapter-dlt")                    (5)
            .autoStartDltHandler(false)                        (6)
            .create(template);
}
1 Maximum of 5 processing attempts (1 initial + 4 retries)
2 Exponential backoff starting at 60 seconds with multiplier 5: delays are 60s, 300s (~5min), 1500s (~25min), 7500s (~2h)
3 Retry topic naming: <original-topic>-fscd-adapter-retry
4 Only ForwardToRetryTopicException triggers the retry mechanism; all other exceptions move to dead-letter topic
5 Dead-letter topic naming: <original-topic>-fscd-adapter-dlt
6 Dead-letter topic handler requires manual configuration for reprocessing

The FS-CD Adapter distinguishes between transient and persistent failures through custom exception types:

  • ForwardToRetryTopicException - for transient failures (network issues, temporary SAP unavailability) that should be retried automatically

  • ForwardToDeadLetterTopicException - for persistent failures (validation errors, missing data, configuration issues) that require manual intervention

Multi-System Support

The integration layer supports processing events from multiple IPM and ICS systems through dynamic client instantiation based on the event’s origin.

This is achieved through:

  • ClientCache<T>: A thread-safe cache that creates and stores REST client instances per base URL

  • FscdAdapterProperties.companies: Configuration that maps base URLs to origin system identifiers and connection properties

  • Dynamic client creation in Reader classes based on the TxoEvent.baseUrl field

For multi-system support to work, the Origin System Configuration must define all connected systems.

For how bidirectional traceability is established see chapter BCON fields.

Polymorphic DTO Support

The IPM REST API may return line-of-business or project-specific DTO subtypes that are unknown to the FS-CD Adapter and not required for the integration.

To avoid having to register unnecessary subtypes, the FS-CD Adapter uses a BaseTypeDeserializationProblemHandler that allows to deserialize unknown subtypes as

  1. their base type e.g., HmContractDto as ContractDto,

  2. a specific type or KfPolicyVersionDto as VbPolicyVersionDto

The handler is configured in the *Reader classes (e.g., IbPolicyEditingReader, VbPolicyEditingReader) when creating their ObjectMapper instances for REST client deserialization.

Refer to the javadoc of BaseTypeDeserializationProblemHandler and its usage for details.