Integration Guide

This guide describes the steps to perform in the modules of the Faktor Zehn suite to integrate with the FS-CD Adapter.

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

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

Enable the editing-finished Event in IPM

In order to publish an editing-finished event, a TxoEntry needs to be written with the same database transaction that finalizes the policy editing in IPM. For this purpose IPM provides the IPS Product Component Type EditingFinishedLifecycleListener.

  1. Add dependency de.faktorzehn.commons:f10-commons-txoutbox-repository to IPM.

  2. Define a new IPS Product Component for IPS Product Component Type de.faktorzehn.ipm.core.model.process.EditingFinishedLifecycleListener with legacyExternalSystemNotification = false and system = default.

  3. Add the Product Component to the Lifecycle Listeners association of all relevant editing definitions for which to publish an event.

  4. Set property txo.base-url-property-name to ipm.base-url.intern.

For integrations with an IPM < 25.7, the External System Notification mechanism is required. Please reach out to the Faktor Zehn product development.

Enable the reserve-changed Event in ICS

In order to publish a reserve-changed event, a TxoEntry needs to be written with the same database transaction that sets the reserve change to 'released' in ICS. For this purpose ICS provides a Maven dependency with a Spring AutoConfiguration.

  1. Add dependency de.faktorzehn.ics:ics-txo-reserves to ICS.

  2. Set property txo.base-url-property-name to ics.callback.base-url.

Enable the payment-transferred and payment-failed Events in ICS

In order to publish a payment-transferred and payment-failed event, a TxoEntry needs to be written with the same database transaction that sets the claim payment to 'transfer successful' / 'failed' in ICS. For this purpose ICS provides a Maven dependency with a Spring AutoConfiguration.

  1. Add dependency de.faktorzehn.ics:ics-txo-payment to ICS.

  2. Set property txo.base-url-property-name to ics.callback.base-url.

Enable the receivable-transferred Event in ICS

In order to publish a receivable-transferred event, a TxoEntry needs to be written with the same database transaction that sets the receivable to 'transfer successful' in ICS. For this purpose ICS provides a Maven dependency with a Spring AutoConfiguration.

  1. Add dependency de.faktorzehn.ics:ics-txo-receivables to ICS.

  2. Set property txo.base-url-property-name to ics.callback.base-url.

Deploy the Kafka Publisher

The kafka publisher processes the TxoEntries and publishes messages to Kafka. For this purpose you can bundle your own SpringBootApplication based on de.faktorzehn.commons:f10-commons-starter-txoutbox-kafka-publisher (for a sample see de.faktorzehn.commons:f10-commons-txo-kafka-publisher-sample) or use the docker image harbor.faktorzehn.de/images/f10-commons-txo-kafka-publisher-sample with the following minimal configuration.

docker-compose.yml
service:
  ${app}-kafka-publisher: (1)
    image: harbor.faktorzehn.de/images/f10-commons-txo-kafka-publisher-sample:${image-tag}
    depends_on:
      ${kafka}: (2)
        condition: service_healthy
    environment:
      f10-commons.txo.kafka-publisher.client-id: ${app}-kafka-publisher
      f10-commons.txo.kafka-publisher.event-name-prefix: "${my.domain}.${app}.event." (3)
      spring.kafka.bootstrap-servers: ${bootstrap-servers} (4)
      spring.datasource.username: ${username} (5)
      spring.datasource.password: ${password}
      spring.datasource.driver-class-name: ${driver-class-name}
      spring.datasource.url: ${jdbc-url}
1 Name of the kafka publisher service, e.g. ipm-kafka-publisher. Each database (IPM, ICS, etc) requires its own kafka publisher.
2 Name of the kafka broker service. depends_on prevents the publisher from producing events before the kafka broker.
3 Prefix for the editing-finished event used as Kafka topic, e.g. de.faktorzehn.ipm.event..
4 Bootstrap servers URL internal to the docker network, for instance redpanda:9092.
5 Data source properties.

Deploy the FS-CD Adapter

Define a docker image for your adapter app and the JCo library.

This assumes all required properties are defined in the app’s application.yml (see git repository fscd-adapter-sample for a fully configured reference implementation).

  • fscd-adapter.companies

  • fscd-adapter.origin-system

  • fscd-adapter.policy-editing.strategy - available values pnc for IPM P&C, shuk for IPM SHU/KF

  • fscd-adapter.policy-editing.mapping

  • fscd-adapter.reserve-change.mapping

  • fscd-adapter.claim-payment.mapping

  • fscd-adapter.receivable.mapping

— except for those explicitly set in the docker-compose.yml below.

Dockerfile
FROM harbor.faktorzehn.de/suite-base/spring:${tag}

COPY sapjco3 /usr/java/packages/lib
COPY fscd-adapter-webapp.jar application.jar
docker-compose.yaml
service:
  fscd-adapter:
    image: ${image-name} (1)
    depends_on:
       - ${kafka} (2)
    environment:
      jco.client.ashost: ${hostname} (3)
      jco.client.r3name: ${r3name}
      jco.client.sysnr: ${sysnr}
      jco.client.lang: ${lang}
      jco.client.client: ${client}
      jco.client.passwd: ${password}
      jco.client.user: ${username}
      spring.kafka.bootstrap-servers: ${bootstrap-servers} (4)
      fscd-adapter.origin-system.ipm-shu.base-urls.internal: ${ipm-shu-base-url-internal} (5)
      fscd-adapter.origin-system.ipm-shu.base-urls.external: ${ipm-shu-base-url-external} (6)
      fscd-adapter.origin-system.ipm-shu.insurance-object-ui-path: ${ipm-view-policy-path} (7)
      fscd-adapter.origin-system.ipm-shu.rest-path: /rest (8)
      fscd-adapter.origin-system.ipm-kf.base-urls.internal: ${ipm-kf-base-url-internal}
      fscd-adapter.origin-system.ipm-kf.base-urls.external: ${ipm-kf-base-url-external}
      fscd-adapter.origin-system.ipm-kf.insurance-object-ui-path: ${ipm-view-policy-path}
      fscd-adapter.origin-system.ics-shu.base-urls.internal: ${ics-base-url-internal}
      fscd-adapter.origin-system.ics-shu.base-urls.external: ${ics-base-url-external}
      fscd-adapter.origin-system.ics-shu.insurance-object-ui-path: ${ics-view-claim-path}
1 Name of your docker image.
2 Name of the kafka service.
3 JCo destination configuration. See Spring ConfigurationProperties JcoProperties.
4 Bootstrap servers URL internal to the docker network, for instance redpanda:9092.
5 The internal URL to access the respective origin system (IPM, ICS, etc.) from within the internal network, used for API requests. E.g. http://ipm-shu:8080. The URL must match the kafka event’s baseUrl.
6 The external URL to access the respective origin system from e.g. browsers, used to construct Links on the Web UI. E.g. https://ipm-shu.example.com.
7 The URI path template used to construct the link to view the respective insurance object in the origin system, for example the "view policy details" page of IPM (/ui/policies/%s/%s) or the "view claim details" page of ICS (/ui/claims/%s).
8 The REST-path prefix used to construct the baseUrl of the WebClients. Defaults to /rest.

Deserialization of Polymorph DTOs

If the IPM editing and version REST service returns DTO subtypes, for instance of ContractBundleDto or VersicherungDto, there are two options:

  1. Bundle the extapi dependencies into the adapter app and configure the packages containing the DTOs via property fscd-adapter.policy-editing.client-subtype-packages. This will automatically scan and register classes ending on Dto with the PolicyEditingClient and PolicyVersionClient used to read data from IPM. To register additional subtypes, override the configured BusinessObjectReader (see PolicyEditingEventListenerAutoConfiguration).

  2. For the standard integration to work, subtypes are not required. To deserialize subtypes as their base types, for instance deserialize ExtContractBundleDto as ContractBundleDto, set property fscd-adapter.policy-editing.base-type-deserialization-pattern to match all subtypes. Its default value is ^de.faktorzehn...extapi.$.

Using the Account Info Tool

Module de.faktorzehn.fscd-adapter:fscd-adapter-account-infotool provides a Linkki InfoTool that can be used in a Linkki webapp, for instance in IPM’s PolicyToolInfos.

Add the Maven dependency of the info tool.

 <dependency>
    <groupId>de.faktorzehn.fscd-adapter</groupId>
    <artifactId>fscd-adapter-account-infotool</artifactId>
    <version>${fscd-adapter.version}</version>
</dependency>

Configure the info tool.

@Component
public class MyLobUI implements IbLobUI {

    @Override
    public PolicyToolInfos createPolicyTools(PolicyUiState policyUiState) {
        var tools = super.createPolicyTools(policyUiState);

        // get the auto-configured FscdAdapterClient
        var fscdAdapterClient = BeanUtils.getOptionalBean(FscdAdapterClient.class);

        if (fscdAdapterClient.isPresent()) {
            var partnerNo = ((ContractBundle)policyUiState.getPolicyVersion().getContentRoot())
                    .getPolicyholderPartnerId();
            var policyNo = policyUiState.getPolicy().getPolicyNo();
            var openAccountUrl = PropertyResolver.get().getRequiredPropertyValue("fscd-adapter.open-policy-account-url")
                    .formatted(partnerNo, policyNo);

            var tool = AccountInfoToolCreator
                    .create(partnerNo,
                            policyNo,
                            fscdAdapterClient.get(),
                            openAccountUrl,
                            BeanProvider.get().getBean(PolicyBindingManager.class));

            return tools.with(tool);
        } else {
            return tools;
        }

    }

    // other methods
}

Configure required application properties

# enables the FscdAdapterClientAutoConfiguration
fscd-adapter.enabled=true
# url to the adapter's REST services
fscd-adapter.rest-url=http://${fscd-adapter}/rest
# oauth client registration used by FscdAdapterClient, requires an oauth client registration
f10-commons.rest.client.fscd-adapter-client.oauth2.user-account-registration-id=keycloak
# url to open the policy in the adapter webapp
fscd-adapter.open-policy-account-url=http://${fscd-adapter}/ui/partners/%s/insurance-objects/%s

Monitoring

The adapter currently does not come with any added monitoring capabilities beyond the dead-letter topics and application logs. For development purposes we deploy a Redpanda Console to interact with the broker.