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 policy-finished Event in IPM

In order to publish a policy-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.outbox.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.outbox.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-txoutbox-kafka-publisher with the following minimal configuration.

docker-compose.yml
service:
  ${app}-kafka-publisher: (1)
    image: harbor.faktorzehn.de/images/f10-commons-txoutbox-kafka-publisher:${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.yaml:

  • fscd-adapter.policy-editing.strategy - available values pnc for IPM P&C, shu for IPM SHUR, kf for IPM KF

  • fscd-adapter.policy-editing.mapping - see git repository fscd-adapter-sample

  • fscd-adapter.reserve-change.mapping- see git repository fscd-adapter-sample

— except for those explicitly set in the docker-compose.yaml 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}
      fscd-adapter.policy-editing.ipm-base-url: ${ipm.base-url.internal} (4)
      fscd-adapter.reserve-change.ics-base-url: ${ics.base-url.internal} (5)
      spring.kafka.bootstrap-servers: ${bootstrap-servers} (6)
1 Name of your docker image.
2 Name of the kafka service.
3 JCo destination configuration. See Spring ConfigurationProperties JcoProperties.
4 URL of the ICS webapp internal to the docker network, for instance http://ipm-webapp:8080.
5 URL of the IPM webapp internal to the docker network, for instance http://ics-webapp:8080.
6 Bootstrap servers URL internal to the docker network, for instance redpanda:9092.

Deserialization of Polymorph DTOs

If the IPM editing 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.editing-client-subtype-packages. This will automatically scan and register classes ending on Dto with the PolicyEditingClient used to read data from IPM. To register additional subtypes, override the configured BusinessObjectReader (see PolicyEditingKafkaListenerAutoConfiguration).

  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.