<dependency>
<groupId>de.faktorzehn.versicherungsmodell</groupId>
<artifactId>vm-basis-extapi</artifactId>
</dependency>
Projekte
ios-basis-extapi
Dieses Schnittstellenmodell ist kompatibel zum alten Schnittstellenmodell des Versicherungsmodells. Weitere Informationen hierzu befinden sich in der Dokumentation des F10-Versicherungsmodells |
-
definiert DTO-Darstellungen des Faktor-IOS Angebotmodells
-
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
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
IosResponseBody
Dieses DTO ist der Ausgangspunkt für die Darstellung aller anderen DTO’s. Sie beinhaltet das AngebotResultDto
oder TAAResultDto
und eine Liste von MessageDto
.
AngebotResultDto
Für spartenspezifische Anwendungen muss dieses DTO abgeleitet werden, um der Klasse die Annotation XmlSeeAlso mit der Angabe der Klassenbezeichnung der spartenspezifischen Versicherung hinzufügen. Dies ist notwendig, um die in den Angebotsvarianten enthaltene Versicherung richtig mappen zu können.
Beispiel für eine Hausrat-spezifische Ableitung:
@XmlSeeAlso(HrVersicherungDto.class)
@XmlRootElement(name = "angebotResult")
public class HrAngebotResultDto extends AngebotResultDto {
// Implementierung wegen XmlSeeAlso für die Darstellung von Hr-Ableitungen
}
Modellklassen-DTO’s
Von den folgenden Modellklassen wurde eine DTO-Darstellung implementiert:
DTO | Modellklasse |
---|---|
AngebotDto |
Angebot und Verkaufsprodukt |
AngebotsVarianteDto |
AngebotsVariante |
RollenDto |
RolesAndPartner |
RolleDto |
Role |
VersicherungsnehmerDto |
Role mit der RoleKind POLICY_HOLDER |
PolicenReferenzDto |
PolicyReference |
Input-Parameter-DTO’s
Die hier aufgelisteten DTO’s können als Input-Parameter für externe Services angewendet werden:
DTO | Beschreibung |
---|---|
AngebotAnlegenDto |
Gibt initiale Daten zum Anlegen von Angeboten weiter. Mitgegeben werden können die Gesellschafts-Id, Verkaufsproduktart-Id, Vermittler-Id, Versicherungsnehmer-Id und das Gültigkeitsdatum. |
AenderungsangebotAnlegenDto |
Gibt initiale Daten zum Anlegen von Änderungsangeboten weiter. Mitgegeben werden können die Policennummer, auf deren zugehörige Police sich das Änderungsangebot beziehen soll, die Vermittler-Id, und das Gültigkeitsdatum. |
TAA-Service-bezogene DTO’s
Für die im Modul ios-basis-extservices
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 an (im Standard sind zusätzlich Rollen 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 Partnerdaten mitgegeben werden, wenn der Partner für eine bestimmte Rolle unbekannt ist. -
AbschliessenDto: Nimmt ein
VersicherungsDto
und weitere für den Service notwendige Daten an (im Standard sind zusätzlich Rollen 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 sowie Partnerdaten mitgegeben werden, wenn der Partner für eine bestimmte Rolle unbekannt ist.
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). Optional können Partnerdaten zu einer Rolle ausgegeben werden.
Partnerbezogene DTO’s
Wenn für einen Service zusätzlich die Anwendung von Partnerdaten bzw. die Kommunikation mit einem externen Partnersystem unterstützt werden soll, können den Input- und Result-DTO’s für einen Service die verschiedenen Partnerbezogenen DTO’s mit hinzugefügt werden.
Input-Parameter-DTO’s
-
PartnerAnlegenDto: Container, das eine Auflistung der eigentlichen Partnerdaten und gegebenenfalls weitere Daten enthalten kann. Die Existenz dieses DTO kann in Services abgefragt werden, um zu entscheiden, ob weitere partnerbezogene Aktionen ausgeführt werden sollen.
-
NeuerPartnerDto: Enthält die eigentlichen partnerbezogenen Daten wie Personendaten, Adressdaten und Bankverbindungsdaten, mit denen man beispielsweise über ein externes Partnersystem Partner anlegen kann. Die Partnernummer kann verwendet werden, um eine Rolle aus einem
VerwaltungsrolleDto
zu referenzieren.
Result-DTO’s
-
PartnerDto: Enthält die partnerbezogenen Daten wie Personendaten, Adressdaten und Bankverbindungsdaten.
Modellklassen-DTO’s
Von den folgenden Modellklassen aus dem Partnerinterface wurde eine DTO-Darstellung implementiert:
DTO | Modellklasse |
---|---|
PersonDto |
Partner |
NatuerlichePersonDto (Ableitung von PersonDto) |
NaturalPerson |
JuristischePersonDto (Ableitung von PersonDto) |
LegalEntity |
AdresseDto |
Address |
BankverbindungDto |
BankAccount oder SepaBankAccount |
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"
}
]
Um die Typinformation trotzdem in der Ausgabe zu bekommen, kann ein sog. MixIn in den ObjectMapper übergeben werden.
package de.faktorzehn.iosexpert.gw.extservices.json;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
import com.fasterxml.jackson.annotation.JsonTypeInfo.Id;
/**
* Erweitert Ableitungen der Basis-Dtos mit dem Typen.
*/
@JsonTypeInfo(use = Id.NAME, include = As.PROPERTY)
public abstract class IosExpertMixIn {
//
}
Anschließend wird eine Konfigurationsklasse erstellt in dem das MixIn in den verwendeten ObjectMapper integriert wird.
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 com.fasterxml.jackson.databind.jsontype.NamedType;
import de.faktorzehn.ios.versicherungsmodell.basis.extapi.partner.JuristischePersonDto;
import de.faktorzehn.ios.versicherungsmodell.basis.extapi.partner.NatuerlichePersonDto;
import de.faktorzehn.ios.versicherungsmodell.basis.extapi.partner.PersonDto;
import de.faktorzehn.versicherungsmodell.basis.extapi.VersicherungDto;
import de.faktorzehn.versicherungsmodell.basis.extapi.VorschadenDto;
import de.faktorzehn.versicherungsmodell.basis.extapi.VorversicherungDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwVersicherungDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwVorschadenDto;
import de.faktorzehn.versicherungsmodell.gw.extapi.GwVorversicherungDto;
/**
* Registriert die abgeleiteten Basis Dtos für Json-Mapping.
*/
@Configuration
public class IosExpertRestJsonConfig {
@Autowired
private ObjectMapper objectMapper;
@PostConstruct
public void addMixIn() {
objectMapper.addMixIn(PersonDto.class, IosExpertMixIn.class);
objectMapper.addMixIn(VersicherungDto.class, IosExpertMixIn.class);
objectMapper.addMixIn(VorversicherungDto.class, IosExpertMixIn.class);
objectMapper.addMixIn(VorschadenDto.class, IosExpertMixIn.class);
// Basis
objectMapper.registerSubtypes(new NamedType(NatuerlichePersonDto.class, "NatuerlichePerson"));
objectMapper.registerSubtypes(new NamedType(JuristischePersonDto.class, "JuristischePerson"));
// Gewerbe-Sach-Haftpflicht
objectMapper.registerSubtypes(new NamedType(GwShVersicherungDto.class, "GwShVersicherung"));
objectMapper.registerSubtypes(new NamedType(GwShVorversicherungDto.class, "GwShVorversicherung"));
objectMapper.registerSubtypes(new NamedType(GwShVorschadenDto.class, "GwShVorschaden"));
}
}
Mit objectMapper.registerSubtypes(…)
kann der Basisklasse und (spartenspezifischen) abgeleiteten Klassen ein Name zur Erkennung des Typs angelegt werden, ohne Json-Annotationen an den Dto-Klassen selbst anlegen zu müssen.
Dadurch wird in der Ausgabe ein neues Attribut "@type" eingefügt mit dem vergebenen Namen der implementierenden DTO-Klasse.
"vorschaeden": [
{
"@type": "GwShVorschaden",
"schadensumme": 32424.0,
"schadenjahr": 2019,
"regulierung": "1",
"regulierungName": "vollständig reguliert",
"gefahr": "1",
"gefahrName": "Feuer"
}
]
XML Marshalling
Es besteht die Möglichkeit, den internen Jaxb2RootElementHttpMessageConverter
durch einen eigenen Marshaller zu ersetzen.
/**
* Hier wird programatisch zu den autom. definierten Convertern von Spring Boot ein Jaxb-Converter
* für die REST Schnittstelle definiert.
*/
@Configuration
public class XmlWebConfig implements WebMvcConfigurer {
/**
* Hier könnt ihr den Marshaller auch registrieren, dann werden aber die Standardmarshaller von Spring Boot nicht registriert. Somit könntet ihr auch json (jackson) oder text selbstständig aufbauen.
*/
@Override
public configureMessageConverters(List<HttpMessageConverter<?>> converters) {
...
}
/**
* Der neue Marshaller wird zu den Standardmarshallern von Spring Boot hinzugefügt.
*/
@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
converters.add(3, marshallingMessageConverter());
}
/**
*Registrierung auch als Bean möglich, aber nicht notwendig.
*/
@Bean
public MarshallingHttpMessageConverter marshallingMessageConverter() {
MarshallingHttpMessageConverter converter = new MarshallingHttpMessageConverter();
converter.setMarshaller(jaxbMarshaller());
converter.setUnmarshaller(jaxbMarshaller());
return converter;
}
@Bean
public Jaxb2Marshaller jaxbMarshaller() {
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
marshaller.setPackagesToScan("de.faktorzehn.ios", "de.faktorzehn.iosexpert",
"de.faktorzehn.versicherungsmodell");
Map<String, Object> props = new HashMap<>();
props.put(javax.xml.bind.Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.setMarshallerProperties(props);
return marshaller;
}
}