Architecture

Idempotency

As mentioned in chapter Event-Driven Integration, the integration layer assumes Faktor Zehn systems use the Transactional Outbox pattern, which requires additional considerations.

At-Least-Once Delivery Guarantee

Message brokers like Kafka provide at-least-once delivery guarantees:

  • Every message is delivered to consumers at least once

  • No messages are lost

  • Under certain failure conditions (e.g., network issues, consumer crashes), messages may be delivered more than once

Consumers of such event messages must guarantee idempotent handling: Processing the same message multiple times must have no additional effect beyond the first processing. Idempotent handling ensures consistent behavior during retries and partial failures.

Idempotent Consumers in FS-CD

The FS-CD Adapter ensures idempotent handling through deterministic identifier assignment and FS-CD’s built-in duplicate detection.

Insurance Object Creation/Updates: The SAP FS-CD RFC for maintaining insurance objects (FSCD_INSOBJECT_MAINTAIN) is inherently idempotent. Calling it multiple times with the same data produces the same result.

Posting Creation: The RFC for creating postings (ISCD_SCPOS_MAINTAIN) is not idempotent. However, FS-CD implements internal duplicate detection: it rejects duplicate postings (same POSNR for the same VTREF) with error code 202.

The FS-CD Adapter leverages this mechanism by:

  • Assigning deterministic, unique identifiers that remain stable across message reprocessing

  • Treating FS-CD error code 202 as a successful idempotent operation rather than a failure

This approach eliminates external tracking databases, making FS-CD the single source of truth.

Unique Identification Numbers

Identification numbers must satisfy three requirements for correct idempotency:

  • Globally unique across all Faktor Zehn systems and object types

  • Deterministic - the same business object always produces the same identifiers (no timestamps, random values, or event metadata)

  • Collision-free within their scope through type prefixes/suffixes where necessary

This approach supports multiple systems with separate databases, provided their business numbers meet these constraints.

Key identifier fields:

Insurance Object Reference Number (VTREF)

Must be globally unique across all policies, claims, commissions, reserves, and receivables. Each posting references an insurance object via this reference number (Posting.insuranceObject.referenceNo) with a maximum length of 20 characters. Type-specific suffixes (e.g., -RES, -CLM) prevent collisions between different object types.

Posting Position Number (POSNR)

Must be unique within each insurance object. Each posting has a position number (Posting.positionNo, SAP field POSNR) with a maximum length of 10 characters. Only needs to be unique per insurance object, not globally.

Business Process Number (GSFNR)

Must uniquely identify the business process across systems. Each posting has a business process number (Posting.businessProcessNo, SAP field GSFNR) with a maximum length of 16 characters. Type prefixes (e.g., C for reserve changes, P for payments) prevent collisions between process types.

Default Assignment Logic

The following tables describe the default number assignment patterns implemented in the mapper classes. The assignment can be customized by overriding the respective *InsuranceObjectMapper and *PostingMapper classes.

Insurance Object Reference Number (VTREF):

Source Object Assignment Logic Example

IPM Policy

${policy-number}

94000212

ICS Claim Payment

${claim-number}

10011

ICS Reserve Change

${claim-number}-RES

10011-RES

ICS Receivable

${claim-number}-${receivable-position-number}

10011-001

Type-specific suffixes prevent collisions between different claim-related objects.

Posting Position Number (POSNR):

Source Object Assignment Logic Example

IPM Posting

${posting-id}

42

ICS Reserve Change

${reserve-change-position-number}

1

ICS Claim Payment

${payment-position-number}-${benefit-type-id}

1-MED

ICS Failed Claim Payment

${payment-position-number}-${benefit-type-id}R

1-MEDR

ICS Receivable

${receivable-position-number}

1

Benefit type suffixes distinguish multiple postings within a payment, reversal suffix (R) distinguishes failed payment corrections.

Business Process Number (GSFNR):

Source Business Process Assignment Logic Example

IPM Policy Editing

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

94000212-1

ICS Reserve Change

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

10011-C1

ICS Claim Payment

${claim-number}-P${payment-position-number}

10011-P1

ICS Receivable

${claim-number}-${receivable-position-number}

10011-R001

Type prefixes (C for reserve changes, P for payments, R for receivables) prevent collisions between different process types.

See BCON Fields for how these identifiers are mapped to SAP FS-CD fields.