Projekte

ios-basis-extapi 2

Dieses Schnittstellenmodell ist kompatibel zum neuen Schnittstellenmodell des Versicherungsmodells. Weitere Informationen hierzu befinden sich in der Dokumentation des F10-Versicherungsmodells

  • definiert DTO-Darstellungen des Faktor-IOS Angebotmodells, die für TAA-Services relevant sind

  • definiert Abhängigkeiten zum Versicherungsmodell-Basis-Extapi für DTO-Darstellungen für die Versicherung und ihrer Komponenten, die Teil der Angebotsvariante sind

  • stellt DTO’s bereit, die als Input-Parameter für externe Services zum Durchführen von angebotsbezogenen Operationen angewendet werden können

<dependency>
	<groupId>de.faktorzehn.versicherungsmodell</groupId>
	<artifactId>vm-basis-extapi2</artifactId>
</dependency>

Result-DTO’s

Die Grundstruktur von DTO’s, die von den externen Services als Ausgabe zurückgegeben werden, beinhalten folgende Komponenten:

  • data: Die fachlichen Daten und Informationen nach dem erfolgreichen Ausführen des Services. Wenn Fehlermeldungen vom Schweregrad Error enthalten sind, sind die Daten in der Regel null.

  • messages: Meldungen, die beim nicht einwandfreien Ausführen des Services zurückgegeben werden. Wenn Fehlermeldungen vom Schweregrad Error enthalten sind, sind fachliche Informationen in der Regel nicht enthalten.

Allgemeine Angebotsbezogene DTO’s

Modellklassen-DTO’s (Basis-Services)

Für Services auf Basis-Ebene wurde von den folgenden Modellklassen eine DTO-Darstellung implementiert:

DTO Modellklasse

RollenDto

RolesAndPartner

VersicherungsnehmerDto

Role mit der RoleKind POLICY_HOLDER

SepaMandatDto

SepaMandat

Für die 'Role mit der RoleKind PREMIUM_PAYER' und 'Role mit der RoleKind CORRESPONDENCE_RECIPIENT' werden jeweils das BeitragszahlerDto und KorrespondenzempfaengerDto des Versicherungsmodells verwendet.

Modellklassen-DTO’s (Angebotsauskunft)

Für die DTO’s aus der Angebotsauskunft wurden folgende Erweiterungen für die Basis-Ebene erstellt:

IOS-Core IOS-Basis Anmerkung

OfferDto

VbOfferDto

Fügt die Vorversicherungsinfo des F10-Versicherungsmodells und das Sepa Mandat hinzu.

OfferVariantDto

VbOfferVariantDto

Fügt die Versicherung des F10-Versicherungsmodells als konkretes Vereinbarungsmodell zur Angebotsvariante hinzu.

Für spartenspezifische Anwendungen müssen unter Jackson die oben genannten Klassen sowie die Klassen der spartenspezifischen Versicherung, Vorversicherung und des Vorschadens als Subtyp im ObjectMapper mit 'registerSubtypes(Class<?>…​)' hinzugefügt werden. Das ist notwendig, um die Erweiterungen des Angebotsmodells und die Komponenten des Versicherungsmodells richtig mappen zu können.

//Basis
objectMapper.registerSubtypes(VbOfferDto.class, VbOfferVariantDto.class)

//Sparte
objectMapper.registerSubtypes(GwShVersicherungDto.class, GwShVorversicherungDto.class, GwShVorschadenDto.class)

Wenn das Schnittstellenmodell erweitert werden soll, muss bei der jeweiligen Ableitung des DTO die Annotation JsonTypeName hinzugefügt werden, die in der Regel den Namen der Klasse enthält. Unter Jackson müssen anschließend noch die Klasse als Subtyp im ObjectMapper hinzugefügt werden.

Beispiel für eine Hausrat-spezifische Ableitung:

@JsonTypeName("HrOfferDto")
public class HrOfferDto extends VbOfferDto {
    // Weitere Attribute
}

Weitere Informationen zum Schnittstellenmodell der Core-Ebene befinden sich in der IOS-Core Dokumentation.

TAA-Service-bezogene DTO’s

Für die im Modul ios-basis-extservices2 eingeführten versicherungsbezogenen TAA-Services werden folgende Dtos zur Verfügung gestellt:

Input-Parameter-DTO’s

  • TarifierungDto: Nimmt ein VersicherungsDto an. Da das Input-DTO der Versicherung spartenabhängig ist, ist die Klasse abstrakt und besitzt einen abstrakten Getter. In einer konkreten Ableitung muss das spartenspezifische Attribut ergänzt werden.

  • AnbietenDto: Nimmt ein VersicherungsDto und weitere für den Service notwendige Daten (Rollen, Partnerdaten und Verkaufsproduktart enthalten). Da das Input-DTO der Versicherung spartenabhängig ist, ist die Klasse abstrakt und besitzt einen abstrakten Getter. In einer konkreten Ableitung muss das spartenspezifische Attribut ergänzt werden.

  • AbschliessenDto: Nimmt ein VersicherungsDto und weitere für den Service notwendige Daten (Rollen, Partnerdaten und Verkaufsproduktart enthalten). Da das Input-DTO der Versicherung spartenabhängig ist, ist die Klasse abstrakt und besitzt einen abstrakten Getter. In einer konkreten Ableitung muss das spartenspezifische Attribut ergänzt werden. Optional können Vorversicherungs- und Vorschadendaten mitgegeben werden.

Result-DTO’s

  • TAAResultDto: Enthält nach der Ausführung des Serviceaufrufs das eingegebene VersicherungsDto, in der die berechneten Beiträge ergänzt wurden, vorhandene Vorversicherungs- und Vorschadendaten, gegebenenfalls weitere berechnete Daten (z.B. ermittelte Risikozonen über die Hausratversicherung) sowie weitere relevante Angebotsdaten (im Standard sind zusätzlich Business-Id, Angebotsnummer und Angebotsstatus enthalten).

Partnerbezogene DTO’s

Wenn für einen Service zusätzlich die Anwendung von Partnerdaten unterstützt werden soll, können die DTOs der Faktor-IBP-Schnittstelle mit hinzugefügt werden. Beispiele dafür befinden sich in AnbietenDto, AbschliessenDto und TAADataDto.

JSON Marshalling

Bei der JSON Ausgabe fehlt normalerweise der Typ der Klasse und man erkennt nur an den zusätzlichen Attributen, dass der korrekte Typ verwendet wurde. Dies kann dazu führen, dass das unmarshalling für die Ableitung nicht korrekt funktioniert.

"vorschaeden": [
    {
      "schadensumme": 32424.0,
      "schadenjahr": 2019,
      "regulierung": "1",
      "regulierungName": "vollständig reguliert",
      "gefahr": "1",
      "gefahrName": "Feuer"
    }
  ]

Über die JsonTypeInfo und JsonTypeName Annotationen ist in den DTOs ist das Attribut @type enthalten, die einen Namen beinhaltet, mit dem das konkrete DTO aufgelöst werden kann.

Um die Typinformation aus dem Attribut @type auswerten zu können und in der Ausgabe zu bekommen, kann eine Konfigurationsklasse erstellt werden, in dem die Subtypen in den verwendeten ObjectMapper registriert werden.

package de.faktorzehn.iosexpert.web.extservices.json;

import jakarta.annotation.PostConstruct;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;

import com.fasterxml.jackson.databind.ObjectMapper;

import de.faktorzehn.ios.versicherungsmodell.basis.extapi2.partner.JuristischePersonDto;
import de.faktorzehn.ios.versicherungsmodell.basis.extapi2.partner.NatuerlichePersonDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwVersicherungDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwShVorschadenDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwShVorversicherungDto;

/**
 * Registriert die abgeleiteten Basis Dtos für Json-Mapping.
 */
@Configuration
public class IosExpertRestJsonConfig {

    @Autowired
    private ObjectMapper objectMapper;

    @PostConstruct
    public void addSubtypes() {

        // Basis
        objectMapper.registerSubtypes(NatuerlichePersonDto.class, JuristischePersonDto.class);

        // Gewerbe-Sach-Haftpflicht
        objectMapper.registerSubtypes(GwShVersicherungDto.class, GwShVorversicherungDto.class, GwShVorschadenDto.class);
    }

}

Dadurch wird anhand des Attributs @type dann die konkret implementierte DTO-Klasse aufgelöst.

"vorschaeden": [
    {
      "@type": "GwShVorschaden",
      "schadensumme": 32424.0,
      "schadenjahr": 2019,
      "regulierung": "1",
      "regulierungName": "vollständig reguliert",
      "gefahr": "1",
      "gefahrName": "Feuer"
    }
  ]