Integration Guide

Integration Deployment

This chapter describes how to deploy the integration by

  1. enabling the transactional outbox in the source systems

  2. publishing domain events for those entries to the message broker using the transactional outbox kafka publisher

  3. deploying and configuring the FS-CD Adapter app

A reference deployment using docker compose can be found in the fscd-adapter-sample git repository (available to Faktor Zehn users only).

The integration requires a message broker compatible with the Apache Kafka API, for instance, Kafka, Redpanda or a cloud-native service. The setup is beyond the scope of this guide.

Enable the Transactional Outbox in IPM

To write entries to the transactional outbox when a policy editing is finished in IPM, follow Benachrichtigung externer Systeme (German).

Property txo.base-url-property-name is usually set to ipm.base-url.intern.
For integrations with an IPM < 25.7 or based on Jakarta EE, the External System Notification mechanism must be used. Please reach out to the Faktor Zehn product development.

Enable the Transactional Outbox in ICS

To write entries to the transactional outbox for reserve changes, payments and receivables, see Verwendung der Transactional Outbox in ICS (German).

Property txo.base-url-property-name is usually set to ics.callback.base-url.
The ICS integration requires the claim to be linked to a company as the company is mapped to FS-CD concepts.

Publish the payment-returned Event in FS-CD

This event is published to the message broker by FS-CD via the processing of so-called Information Containers. The exact implementation depends on the message broker API and the client libraries available for FS-CD. It is a project-specific customization in FS-CD and not covered in this guide.

Deploy the Transactional Outbox Kafka Publisher

The kafka publisher processes the entries of a transactional outbox and publishes messages to the message broker. One publisher needs to be deployed per outbox.

See Transactional Outbox (German) for how to bundle and deploy a publisher.

Set property f10-commons.txo.kafka-publisher.event-name-prefix to the prefix of the kafka topic, e.g., de.faktorzehn.ipm.event.

Faktor Zehn users may use the docker image harbor.faktorzehn.de/images/f10-commons-txo-kafka-publisher-sample instead of creating their own image.

Deploy the FS-CD Adapter

Define a docker image with the FS-CD Adapter app and the JCo library.

Dockerfile
# only available to Faktor Zehn users, use your own base image
FROM harbor.faktorzehn.de/suite-base/spring:${image-tag}

# assumes a folder with the jco binaries in the docker context root directory
COPY sapjco3 /usr/java/packages/lib
# filename might vary based on Maven project name
COPY target/fscd-adapter-webapp.jar application.jar

All required properties must either be set in the app’s Spring Profiles or as environment variables. This includes the following properties

  • jco.client

  • fscd-adapter.open-partner-url

  • fscd-adapter.companies

  • fscd-adapter.origin-system

  • fscd-adapter.policy.mapping

  • fscd-adapter.reserve-change.mapping

  • fscd-adapter.claim-payment.mapping

  • fscd-adapter.receivable.mapping

  • fscd-adapter.payment-returned

It is recommended to set spring.kafka.listener.ack-mode to record to avoid reprocessing already-successful messages.