Stand: 11.11.2026, Release 9.3.

Anwendung

Diese Seite zeigt, wie Sie als Administrator eines Mandanten Schnittstellen, Keystores und Transaktionen erfassen und pflegen. Das Grundkonzept steht auf der Seite Schnittstellen-Verwaltung.

Voraussetzung ist die Rolle Administrator. In der Administration finden Sie die Unit «Schnittstellen» mit drei Einträgen:

Schnittstellen

Die Übersicht

Die Liste zeigt beim Öffnen alle Schnittstellen Ihres Mandanten und die Schnittstellen übergeordneter Mandanten, die für Sie freigegeben sind.

Die Suchmaske filtert nach Service-Key, Service-Typ, Auth-Typ, Aktiv, URL und Beschreibung. Die Spalte «Beschreibung» lässt sich über die Spaltenauswahl einblenden.

Schnittstellen eines übergeordneten Mandanten erscheinen grau. Sie können sie öffnen, aber nicht ändern.

Schnittstelle erfassen

1. In der Übersicht eine neue Schnittstelle anlegen.
2. Service-Key, Service-Typ und Auth-Typ wählen. Je nach Auth-Typ erscheinen weitere Felder.
3. URL und die Angaben zur Anmeldung ausfüllen.
4. Die Zugangsdaten setzen, siehe «Zugangsdaten setzen».
5. «Speichern».

Felder

Anmerkung: Header und Properties dürfen keine Zugangsdaten enthalten. Ein Name, der wie ein Passwort oder Schlüssel aussieht, wird beim Speichern abgewiesen, ebenso der Header Authorization. Zugangsdaten gehören in die Zeile des Auth-Typs.

Auth-Typen

Anmerkung: Der Service-Typ LDAP lässt nur «Keine Anmeldung» und «Basic» zu. Die Pflichtangaben eines Auth-Typs gelten für eine aktive Schnittstelle; eine deaktivierte darf unvollständig sein.

Zugangsdaten setzen

Die Zeile der Zugangsdaten zeigt nur den Zustand, nie den Wert: «nicht gesetzt», «gesetzt, geändert … von …» oder «neuer Wert gesetzt».

1. In der Zeile auf das Stift-Symbol «Neuen Wert setzen …» klicken.
2. Im Dialog den Wert in «Neuer Wert» und nochmals in «Wert wiederholen» eingeben.
3. «Übernehmen». Die Zeile zeigt «neuer Wert gesetzt».
4. Die Schnittstelle speichern. Erst jetzt wird der Wert verschlüsselt abgelegt.

Wenn Sie den Auth-Typ einer Schnittstelle wechseln, werden die bisherigen Zugangsdaten beim Speichern gelöscht.

Keystore zuordnen

Braucht das Drittsystem ein Client-Zertifikat, oder verwendet es ein Zertifikat, dem Ihr Server nicht von sich aus vertraut, ordnen Sie der Schnittstelle einen Keystore zu. Der Keystore muss vorher in der Liste «Keystores» erfasst sein.

Die Auswahl zeigt Name, Typ und Ablaufdatum jedes Keystores. Verwenden weitere Schnittstellen denselben Keystore, nennt das Formular sie unter «Keystores auch verwendet von».

Speichern, aktivieren, deaktivieren

Ist eine Angabe unzulässig oder fehlt eine Pflichtangabe, bleibt das Formular offen, und die Statuszeile nennt alle Gründe: «Die Schnittstelle kann nicht gespeichert werden: …».

Schnittstelle prüfen: Diagnose

Das Stethoskop-Symbol «Diagnose» in der Zeile einer Schnittstelle zeigt, was ein Formular oder eine Transaktion Ihres Mandanten mit diesem Service-Key tatsächlich erhält.

• Herkunft: die eigene Schnittstelle, eine freigegebene Schnittstelle eines übergeordneten Mandanten oder eine bisherige Konfigurationsdatei («Legacy-Datei»).
• Mandant: der Mandant, für den die Diagnose gilt.
• Typ, URL, Benutzername, Properties.
• Secrets: pro Zugangswert «lesbar» mit der Länge oder «nicht lesbar» mit dem Grund. Nie der Wert.
• Keystores: Name, Typ und Ablaufdatum.

Die Diagnose baut keine Verbindung zum Drittsystem auf. Sie prüft, ob die Angaben vollständig und die Zugangsdaten lesbar sind, nicht, ob das Drittsystem sie annimmt.

Schnittstelle löschen

1. Die Schnittstelle öffnen und «Deaktivieren».
2. In der Übersicht die Zeile ankreuzen und den Papierkorb wählen.

Löschen lassen sich nur eigene und nur deaktivierte Schnittstellen. Die Zugangsdaten der Schnittstelle werden mitgelöscht. Zugeordnete Keystores bleiben bestehen.

Keystores

Ein Keystore ist eine Zertifikatsdatei zusammen mit ihrem Passwort. Sie erfassen ihn einmal und ordnen ihn beliebig vielen Schnittstellen zu. Läuft ein Zertifikat ab, ersetzen Sie die Datei an einer Stelle.

Die Liste

Die Liste zeigt nur die Keystores Ihres Mandanten. Keystores werden nicht an untergeordnete Mandanten weitergegeben.

Keystore erfassen

1. In der Liste einen neuen Keystore anlegen.
2. Name und Art wählen.
3. In der Zeile «Datei» auf «Datei und Passwort hochladen …» klicken.
4. Im Dialog zuerst die Datei wählen (.p12, .pfx, .jks oder .jceks, höchstens 1'024 KB), dann das Passwort eingeben. Bei einem Truststore ist das Passwort freiwillig.
5. Der Dialog prüft die Datei sofort und zeigt ihre Einträge mit Ablaufdatum.
6. «Übernehmen».
7. Den Keystore speichern. Erst jetzt werden Datei und Passwort verschlüsselt abgelegt.

Hinweise der Prüfung

Lässt sich die Datei mit dem Passwort nicht öffnen, nimmt der Dialog sie nicht an: «Der Keystore lässt sich nicht öffnen: …».

Öffnet sich die Datei, zeigt der Dialog zusätzlich Warnungen. Sie verhindern das Speichern nicht, weisen aber auf ein Risiko hin. Die Warnungen erscheinen in englischer Sprache.

Zertifikat erneuern

1. Den Keystore öffnen.
2. «Datei und Passwort hochladen …» und die neue Datei mit ihrem Passwort angeben.
3. Der Dialog nennt, für wie viele und welche Schnittstellen die neue Datei gelten wird.
4. «Übernehmen» und den Keystore speichern.

Die neue Datei gilt danach für alle Schnittstellen, die den Keystore verwenden. Das Passwort lässt sich nur zusammen mit einer Datei setzen.

Keystore löschen

Ein Keystore lässt sich nur löschen, wenn ihn keine Schnittstelle mehr verwendet. Entfernen Sie zuerst die Zuordnung in den Schnittstellen. Datei und Passwort werden mitgelöscht.

Transaktionen

Eine Transaktion beschreibt, was beim Aufruf eines Drittsystems geschieht: eine geordnete Folge von Schritten. Jeder Schritt nennt eine Implementation und deren Eigenschaften. Die Zugangsdaten stehen nie in der Transaktion, sondern in der Schnittstelle, auf die sie verweist.

Die Liste

Die Liste zeigt die Transaktionen Ihres Mandanten mit ID, UUID, Name sowie dem Zeitpunkt der Erstellung und der letzten Änderung. Die Suchmaske filtert nach ID und Name. Mit «Neues Element hinzufügen» legen Sie eine Transaktion an, mit «Öffnen» bearbeiten Sie eine bestehende.

Aufbau einer Transaktion

Jeder Schritt hat diese Felder:

Eine Eigenschaft besteht aus:

REST-Aufruf über eine Schnittstelle

Für einen REST-Aufruf besteht die Transaktion aus einem Rahmen und einem oder mehreren Unterschritten:

Der Rahmen verweist mit der Eigenschaft serviceId auf die Schnittstelle. Ihr Wert ist der Service-Key.

Schritt 1  Implementation: SequentialGenericRESTHandler
           serviceId = {SERVICE_KEY}

  Unterschritt 1.1  Implementation: GenericRESTJsonStepCommand
                    path                 = /v1/addresses/${xpath:/Formular/Adresse/Plz}
                    httpMethod           = GET
                    expectedResponseCodes = 200
                    transformIn          = {RESPONSE_MAPPING_RESOURCE}

Aus der Schnittstelle kommen die Basis-URL, die Anmeldung, die statischen Header und, falls zugeordnet, das Client-Zertifikat. In der Transaktion steht nur, was den einzelnen Aufruf ausmacht.

Eigenschaften eines REST-Unterschritts

Weitere Arten von Schritten

Transaktion testen

Es gibt keinen Knopf, um eine Transaktion direkt auszuführen. Setzen Sie für einen Test die Eigenschaft mode auf simulation oder logging und lösen Sie die Transaktion über das Formular aus. Prüfen Sie vorher die Schnittstelle mit der Diagnose.

Transaktion auslösen

Eine Transaktion läuft, wenn ein Formular sie auslöst. Die Zuordnung geschieht im Service-Descriptor des Formulars, im Abschnitt «Schnittstellen»: Dort wählen Sie die Transaktion, aktivieren sie und legen fest, bei welchem Status sie läuft und welchen Status das Formular danach erhält.

Transaktion löschen

In der Liste die Zeilen ankreuzen und «Alle ausgewählten Einträge löschen» wählen. Das System prüft nicht, ob ein Formular die Transaktion noch verwendet.

Bekannte Probleme

«Die Schnittstelle kann nicht gespeichert werden: BASIC braucht ein Secret für BASIC_PW»

Problem

Die Schnittstelle ist aktiv, aber die Zugangsdaten sind nicht gesetzt. Die Meldung verwendet technische Namen: BASIC_PW ist das Passwort, API_KEY_VALUE der API-Key, OAUTH2_CLIENT_SECRET das Client-Secret.

Lösung

Den Wert über «Neuen Wert setzen …» eingeben und erneut speichern.

«Der Header … sieht wie ein Secret aus»

Problem

Ein statischer Header oder eine Property trägt einen Namen, der auf Zugangsdaten hinweist.

Lösung

Den Wert nicht als Header oder Property erfassen, sondern den passenden Auth-Typ wählen und den Wert dort setzen.

«Speichern fehlgeschlagen. Die Schnittstelle wurde durch einen anderen Benutzer modifiziert.»

Problem

Jemand hat die Schnittstelle geändert, während Sie sie geöffnet hatten.

Lösung

Die Schnittstelle neu öffnen und die Änderung wiederholen.

«Deaktivieren Sie die Schnittstelle vor dem Löschen.»

Problem

Eine aktive Schnittstelle lässt sich nicht löschen.

Lösung

Die Schnittstelle öffnen, «Deaktivieren» wählen und danach löschen.

Eine Transaktion bricht ab: «differ from the definition of service»

Problem

Die Transaktion setzt scope, tokenAuthMethod oder apiKeyHeader mit einem anderen Wert als die Schnittstelle.

Lösung

Die Eigenschaft aus der Transaktion entfernen und den Wert in der Schnittstelle setzen.

Der Aufruf schlägt fehl, obwohl die Diagnose alles als lesbar zeigt

Problem

Die Diagnose prüft nicht, ob das Drittsystem die Zugangsdaten annimmt.

Lösung

Die Zugangsdaten beim Anbieter prüfen und neu setzen. Bei einem Client-Zertifikat das Ablaufdatum in der Liste «Keystores» kontrollieren.

Offene Punkte

• Elf Screenshots aufnehmen und mit den vorgegebenen Dateinamen anhängen
• Beschriftung des Knopfs für eine neue Schnittstelle und einen neuen Keystore in der Oberfläche prüfen und im Text ergänzen
• Prüfen, ob die Felder «Name» und «Beschreibung» einer Transaktion in der Oberfläche als Pflicht gelten
• Diesen Abschnitt vor der Veröffentlichung entfernen