Mapper zwischen epilot und Umsystemen: Aufbau mit Quarkus

Ein Quarkus Mapper für epilot ist ein eigener, kleiner Dienst, der zwischen epilot und Ihren Umsystemen Daten übersetzt. Dieser Artikel zeigt, wie so ein Mapper aufgebaut ist, welche Aufgaben er übernimmt und welche Regeln ihn im Betrieb stabil machen.

Geschrieben hat ihn Marcel R. G. Berger. Ich bin seit über 20 Jahren Softwareentwickler und Softwarearchitekt und arbeite mit epilot als externer Consultant und Entwickler für Apps und Individualisierungen. Der Text richtet sich an IT-Verantwortliche bei Netzbetreibern, Stadtwerken und Energieversorgern, die Umsysteme an epilot anbinden wollen.

Was ist ein Mapper zwischen epilot und Umsystemen?

Ein Mapper ist ein eigener Dienst, der Daten zwischen epilot und einem anderen System übersetzt. Er nimmt Daten in der Form entgegen, in der die eine Seite sie liefert, und gibt sie in der Form weiter, die die andere Seite erwartet.

Das klingt nach einer einfachen Feldzuordnung, ist in der Praxis aber mehr. Ein Mapper erledigt typischerweise fünf Aufgaben.

Aufgabe	Was der Mapper tut	Beispiel
Feldzuordnung	ordnet Felder der einen Seite den Feldern der anderen Seite zu	ein Kundenfeld in epilot wird zum passenden Feld im Fachsystem
Formatumwandlung	wandelt Datentypen, Datumsformate, Codes und Strukturen um	ein Datum im ISO-Format wird zu dem Format, das das Zielsystem erwartet
Validierung	prüft, ob Pflichtangaben vorhanden und Werte plausibel sind	ein Datensatz ohne Pflichtfeld wird abgewiesen statt halb übertragen
Anreicherung	ergänzt Daten aus weiteren Quellen	Stammdaten werden aus einer Datenbank nachgeladen
Fehlerbehandlung	erkennt Fehler, wiederholt Aufrufe und protokolliert nachvollziehbar	ein kurz nicht erreichbares System wird später erneut angesprochen

Der Mapper ist damit die Stelle, an der sich alle Regeln sammeln, die nur deshalb existieren, weil zwei Systeme unterschiedlich ticken. In epilot selbst bleibt nur, was fachlich zu epilot gehört.

Wann lohnt sich ein eigener Mapper statt eines Low-Code-Flows?

Ein eigener Mapper lohnt sich, sobald mehr als eine einfache Weitergabe von Daten gefragt ist. Für einfache Fälle bringt epilot selbst Werkzeuge mit, und die sollten Sie zuerst nutzen.

epilot ist eine hervorragende No-Code- und Low-Code-Plattform. Laut der Dokumentation zu Umgebungen und Secrets in epilot Webhooks lassen sich Webhook-Payloads schon in epilot mit JSONata umformen, und Umgebungsvariablen können als Zuordnungstabellen für Codes dienen. Für viele Anbindungen reicht das.

Anders sieht es aus, wenn ein Prozess über mehrere Systeme läuft. Die folgende Übersicht zeigt, wo die Grenze typischerweise liegt.

Anforderung	Low-Code-Flow in epilot	Eigener Mapper
Felder umbenennen und Werte über Tabellen übersetzen	passt gut	nicht nötig
Ein Ziel, eine Richtung, ein Aufruf	passt gut	nicht nötig
Daten aus Datenbank oder weiterem CRM ergänzen	stößt an Grenzen	Anreicherung im Code
Mehrere Umsysteme in einer Abfolge ansprechen	stößt an Grenzen	Ablauf mit Fehlerbehandlung je Schritt
Fachliche Prüfregeln mit Tests absichern	eingeschränkt	Validierung mit automatisierten Tests
Ergebnis zurück nach epilot schreiben	aufwendig	Rückschreiben über die epilot API

Die Tabelle ist eine Orientierung, keine feste Regel. Warum diese Grenze selten bei epilot liegt und fast immer an den Rändern der Plattform, erklärt der Artikel Wann reicht Low-Code bei epilot nicht mehr?.

Wie sieht der Datenfluss einer epilot Schnittstelle mit Quarkus aus?

Der Datenfluss beginnt mit einem Ereignis in epilot und endet mit einer Aktion im Umsystem, oft mit einem Rückschreiben nach epilot. Dazwischen liegt der Mapper als eigener Dienst in einem Container.

1. In epilot tritt ein Ereignis ein, und epilot sendet einen Webhook an den Mapper.
2. Der Mapper prüft, ob die Anfrage wirklich von epilot kommt.
3. Er wandelt die Daten um, prüft sie und ergänzt fehlende Angaben aus weiteren Quellen.
4. Er ruft das Umsystem per REST auf oder löst dort ein Event aus.
5. Bei Bedarf schreibt er das Ergebnis über die epilot API zurück, damit die Information in epilot verfügbar ist.

Die Dokumentation zu den epilot Webhooks beschreibt den ersten Schritt so: Bei einem Ereignis sendet epilot einen HTTP-POST mit signiertem Payload an die hinterlegte URL. Die Dokumentation weist außerdem darauf hin, dass epilot die Payloads mit Transfer-Encoding: chunked überträgt. Ein Quarkus-Dienst kommt damit ohne eigenen Aufwand zurecht.

So arbeite ich auch im aktuellen Projekt bei einem Netzbetreiber in Hessen. Viele Prozesse laufen dort außerhalb von epilot, und mehrere Drittsysteme sind über individuell entwickelte Schnittstellen angebunden. Die Mapper-Tools dafür entstehen in Java mit Quarkus und laufen containerisiert. Mehr dazu steht im Abschnitt Aus der Praxis auf der Startseite.

Wie nimmt ein Quarkus-Dienst einen epilot Webhook entgegen?

Ein Quarkus-Dienst nimmt einen epilot Webhook über eine einfache REST-Ressource entgegen. Eine Klasse mit @Path und eine Methode mit @POST reichen, wie der Quarkus-Leitfaden zu REST-Diensten zeigt.

Wichtig ist die Reihenfolge: erst prüfen, dann verarbeiten. Die Seite zur Sicherheit der epilot Webhooks nennt dafür die Header webhook-id, webhook-timestamp und webhook-signature und empfiehlt, Signaturen immer vor der Verarbeitung zu prüfen.

@Path("/webhooks/epilot")
public class WebhookResource {

    @Inject
    SignatureVerifier verifier;

    @Inject
    MappingService mappingService;

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response receive(@HeaderParam("webhook-id") String messageId,
                            @HeaderParam("webhook-timestamp") String timestamp,
                            @HeaderParam("webhook-signature") String signature,
                            String rawBody) {
        if (!verifier.isValid(messageId, timestamp, signature, rawBody)) {
            return Response.status(Response.Status.UNAUTHORIZED).build();
        }
        mappingService.process(messageId, rawBody);
        return Response.ok().build();
    }
}

Der Body wird hier bewusst als Rohtext angenommen, weil die Signatur über den unveränderten Inhalt berechnet wird. Erst nach der Prüfung wandelt der MappingService den Text in Objekte um. SignatureVerifier und MappingService sind eigene Klassen des Projekts, keine fertigen Bibliotheken.

Signaturprüfung und Idempotenz vertieft der Artikel epilot Webhooks sicher verarbeiten.

Wie spricht der Mapper Umsysteme per REST an?

Der Mapper spricht Umsysteme über einen typisierten REST-Client an. In Quarkus beschreiben Sie die Schnittstelle des Zielsystems als Java-Interface, und das Framework erzeugt die Implementierung.

Der Quarkus-Leitfaden zum REST Client beschreibt dieses Vorgehen auf Basis von MicroProfile REST Client. Die Adresse des Zielsystems steht nicht im Code, sondern in der Konfiguration.

@RegisterRestClient(configKey = "target-system")
@Path("/customers")
public interface TargetSystemClient {

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    Response createCustomer(CustomerPayload customer);
}

In der Konfiguration genügt dann eine Zeile wie quarkus.rest-client.target-system.url=${TARGET_SYSTEM_URL}. Die eigentliche Adresse kommt aus einer Umgebungsvariable, die je nach Umgebung anders gesetzt ist.

Auf dieselbe Weise liefert der Mapper Daten aus Umsystemen wie weiteren CRM-Systemen oder Datenbanken per REST API an epilot. Und er kann in anderen Systemen Events auslösen, etwa indem er eine Nachricht an deren Schnittstelle sendet. Wie eine solche REST-API Schnittstelle für epilot aufgebaut ist, beschreibt ein eigener Artikel.

Warum eignet sich Quarkus für Mapper in Containern?

Quarkus eignet sich für Mapper, weil es von Anfang an für Container gebaut ist. Dienste starten schnell, brauchen wenig Speicher und lassen sich deshalb gut horizontal skalieren.

Für einen Mapper zählt außerdem, was Quarkus als offizielle Erweiterung mitbringt. So bleibt der eigene Code auf die fachliche Übersetzung beschränkt.

• REST-Dienste und REST-Client für Webhooks und Aufrufe von Umsystemen
• Health Checks über SmallRye Health
• Konfiguration über MicroProfile Config
• Beschreibung der eigenen Schnittstelle über OpenAPI
• Fehlertoleranz über SmallRye Fault Tolerance
• Erzeugen von Container-Images direkt aus dem Build

Der Quarkus-Leitfaden zu Container-Images zeigt, wie aus dem Projekt ein Image entsteht. Wer noch kürzere Startzeiten braucht, kann den Dienst nach dem Leitfaden zu nativen Images als natives Programm bauen.

Für den Auftraggeber bedeutet das: Der Mapper ist ein gewöhnliches Java-Projekt mit Maven oder Gradle. Jedes Team mit Java-Erfahrung kann es lesen, bauen und betreiben.

Wie fängt ein Mapper Fehler und Ausfälle von Umsystemen ab?

Ein Mapper fängt Fehler mit Wiederholungen, Zeitlimits und einem Schutzschalter ab. In Quarkus erledigen das Annotationen aus SmallRye Fault Tolerance, ohne dass Sie die Logik selbst schreiben.

Der Quarkus-Leitfaden zu SmallRye Fault Tolerance beschreibt @Retry, @Timeout, @CircuitBreaker und als Erweiterung auch @ExponentialBackoff für wachsende Wartezeiten.

@ApplicationScoped
public class TargetSystemGateway {

    @Inject
    @RestClient
    TargetSystemClient client;

    @Retry(maxRetries = 4, delay = 500, jitter = 200)
    @ExponentialBackoff
    @Timeout(5000)
    @CircuitBreaker(requestVolumeThreshold = 10, failureRatio = 0.5, delay = 30000)
    public void send(CustomerPayload customer) {
        client.createCustomer(customer);
    }
}

Die Werte im Beispiel sind Platzhalter und werden je Umsystem festgelegt. Nicht jeder Fehler sollte wiederholt werden: Ein abgelehnter Datensatz bleibt abgelehnt, egal wie oft er gesendet wird. Über retryOn und abortOn lässt sich genau steuern, welche Fehler eine Wiederholung auslösen.

Auch in Richtung epilot gilt diese Regel. Die Seite zu Rate Limits in der epilot Dokumentation beschreibt, dass die API beim Überschreiten eines Limits mit HTTP 429 antwortet und im Header Retry-After angibt, nach wie vielen Sekunden es weitergehen kann. Ein Mapper, der nach epilot zurückschreibt, sollte diesen Wert beachten.

Warum ist Idempotenz so wichtig?

Idempotenz sorgt dafür, dass ein doppelt zugestellter Webhook keinen doppelten Datensatz erzeugt. Das ist wichtig, weil Wiederholungen auf beiden Seiten vorkommen.

Laut der Dokumentation zum Monitoring der epilot Webhooks lässt sich jedes Webhook-Ereignis in epilot erneut abspielen. Der Header webhook-id ist laut Dokumentation eine eindeutige Kennung der Nachricht. Der Mapper kann sich bereits verarbeitete Kennungen merken und eine zweite Zustellung derselben Nachricht erkennen.

Was braucht ein Mapper für einen stabilen Betrieb?

Ein Mapper braucht für einen stabilen Betrieb Sichtbarkeit, saubere Konfiguration und Tests. Ohne diese Punkte läuft er zwar, aber niemand merkt rechtzeitig, wenn er stockt.

• Health Probes: Quarkus stellt mit SmallRye Health die Endpunkte /q/health/live und /q/health/ready bereit, die eine Container-Plattform abfragen kann. Details stehen im Quarkus-Leitfaden zu SmallRye Health.
• Strukturiertes Logging: Jede Verarbeitung wird mit der Nachrichtenkennung protokolliert, sodass sich ein Datensatz über alle Systeme verfolgen lässt. Der Quarkus-Leitfaden zu Logging beschreibt auch die Ausgabe als JSON.
• Konfiguration und Secrets außerhalb des Codes: Adressen, Schlüssel und Signaturgeheimnisse kommen aus Umgebungsvariablen oder einem Secret-Speicher. Wie Quarkus Werte aus verschiedenen Quellen liest, zeigt die Quarkus-Referenz zur Konfiguration.
• Dokumentierte Schnittstelle: Über die Quarkus-Erweiterung für OpenAPI beschreibt der Mapper seine eigenen Endpunkte unter /q/openapi.

Auf der epilot-Seite hilft das Monitoring der Webhooks. Dort sehen Sie laut Dokumentation Payload, Header und Antwortcode jeder Zustellung, und die Ereignisse werden standardmäßig vier Wochen aufbewahrt.

Wie werden Mapper getestet?

Mapper werden auf zwei Ebenen getestet: die reine Zuordnung mit einfachen Unit-Tests, der ganze Dienst mit @QuarkusTest. Der Quarkus-Leitfaden zum Testen zeigt, wie ein Test die Anwendung startet und Endpunkte mit REST Assured aufruft.

Für jede Zuordnung gibt es Beispieldaten: ein Eingang aus epilot und die erwartete Ausgabe für das Umsystem. Ändert sich eine Regel, zeigt der Test sofort, welche Fälle betroffen sind.

Wie werden Zuordnungen versioniert?

Zuordnungen werden wie Code versioniert, im selben Repository und mit nachvollziehbarer Historie. Jede Änderung an einer Regel läuft über einen Commit, wird getestet und mit einer neuen Version des Containers ausgeliefert.

Ändert ein Umsystem sein Format, kann der Mapper für eine Übergangszeit beide Formate kennen. So lassen sich Umstellungen ohne harten Schnitt durchführen.

Wie Monitoring, Fehlerbehandlung und Wartung im laufenden Betrieb aussehen, beschreibt der Artikel epilot Integrationen im Betrieb.

Wem gehört der Code des Mappers?

Der Code des Mappers gehört Ihnen als Auftraggeber. Auf Wunsch übergebe ich ihn in Ihr eigenes Repository, sodass Ihr Team ihn selbst weiterentwickeln und betreiben kann.

Alternativ übernehme ich Betreuung und Weiterentwicklung über einen Wartungsvertrag. Beide Wege sind möglich, und Sie entscheiden. Warum das für Netzbetreiber besonders wichtig ist, erklärt der Artikel Wem gehört der Integrationscode?.

Dabei ergänze ich das Consulting-Team von epilot, ich ersetze es nicht. epilot bleibt Ihr Ansprechpartner für die Plattform und ihren Standardumfang. Ich setze dort an, wo klassische Entwicklung nötig wird. Welche Leistungen dazu gehören, steht im Abschnitt Was ich für epilot-Kunden mache.

Wie starten Sie mit einem eigenen Mapper?

Sie starten mit einem kostenlosen Erstgespräch, in dem wir Ihre Systeme und Abläufe durchgehen. Danach ist klar, ob die Werkzeuge von epilot reichen oder ob ein eigener Mapper sinnvoll ist.

1. Erstgespräch: kostenlos und unverbindlich, 30 Minuten über Microsoft Teams.
2. Individuelles Angebot: zugeschnitten auf Ihre Umsysteme, Datenformate und Anforderungen an den Betrieb.
3. Umsetzung: Der Mapper wird entwickelt, getestet und mit Ihren Systemen in Betrieb genommen.

Alle Leistungen biete ich auf Basis eines individuellen Angebots an. Antworten auf weitere Fragen finden Sie in den häufigen Fragen auf der Startseite, einen Termin wählen Sie direkt im Buchungskalender.