Overview

Integration Architecture

Integration Flow

The following sequence diagram[1] illustrates the flow from Faktor-IPM to FS-CD using the Transactional Outbox integration pattern.

integration sequence diagram
Description

  1. An event is created in a Faktor Zehn module and inserted into the database[2]

  2. The database is periodically polled for events to process

  3. For each event to process, a Kafka message[3] is produced in a Kafka topic

  4. The event’s status is updated as processed in the database

  5. The adapter listens to the topic and processes each new message

  6. For each message relevant data is read[4] from the Faktor Zehn module

  7. The data is transformed into FS-CD data

  8. A call to FS-CD is made using the SAP Java Connector[5] (JCo)

  9. After processing the messages is marked as consumed

  10. If an error occurred, the message is forwarded to a retry or dead-letter topic

Integration Pattern

The integration uses the Transactional Outbox pattern and an idempotent consumer to achieve consistency.

Transactional Outbox

The Faktor Zehn modules employ an integration pattern known as Transactional Outbox. It ensures reliable event publishing and consistency by writing events to an outbox database table in the same database transaction as the changes to the business data. This means either both business data and event data are written, or none of them.

The events are then asynchronously processed and sent to a message broker (Kafka) to guarantee that events are not lost even if the service crashes before they can be published. See here for more information.

At-Least-Once Guarantee

Kafka’s at-least-once processing guarantees that the consumer will process each message at least once. This ensures no messages are lost. Under certain failure conditions, however, messages may be processed more than once. This case is handled on the consumer-side.

Idempotent Consumer

The consumer of those messages must be implemented to be idempotent in order to handle potential duplicate messages. This means that processing the same message multiple times has no additional effect beyond the first processing. Idempotent handling is critical for ensuring consistent behaviour in the face of retries and partial failures.

Idempotent Consumers in FS-CD

While the FS-CD Remote Function Call (RFC) for maintaining insurance objects is idempotent, the RFC for creating postings is not. However, FS-CD implements internal safeguards: if a posting with the same position number (POSNR) for the same insurance object (VTREF) is submitted more than once, it will be rejected as a duplicate.

The adapter leverages this behaviour to enforce idempotency by:

  • Assigning stable and unique posting position numbers (POSNR) within the context of each insurance object, and

  • Detecting and gracefully handling FS-CD’s duplicate position number error message, treating it as a successful outcome rather than a failure.

Posting Position Number Assignment

Below table depicts the default logic for assigning position numbers. The assignment can be customized.

Object Field Used Explanation

IPM Posting

Posting.id

Unique within an IPM database. Supports multiple IPMs with separate databases as long as policy numbers remain distinct.

ICS Reserve Changes

ReserveChange.positionNumber

Unique within a claim. Supports multiple ICS with separate databases as long as claim numbers remain distinct.
Business Process Number Assignment

While not relevant for idempotency, each posting has an origin business process number (Posting.businessProcessNo, GSFNR) that is assigned as follows. The assignment can be customized.

Object Assignment Logic Explanation

IPM Posting

${policy-number}-${editing-number}

Unique within an IPM database. Supports multiple IPMs with separate databases as long as policy numbers remain distinct.

ICS Reserve Changes

${claim-number}-${reserve-change-position-number}

Unique within an ICS database. Supports multiple ICS with separate databases as long as claim numbers remain distinct.
1. Simplified for clarity and explanation.
2. For instance IPM creates a editing-finished event in the same transaction with the business logic finishing a policy editing
3. A publish-subscribe messaging broker
4. via REST. Can be customized to use the event’s payload
5. Can be customized to SOAP or REST