...
Voraussetzung ist die Rolle Administrator. In der Administration finden Sie die Unit «Schnittstellen» mit drei Einträgen:
| Eintrag | Inhalt |
|---|---|
| Übersicht | Die Schnittstellen Ihres Mandanten: Adresse, Art der Anmeldung, Zugangsdaten. |
| Keystores | Zertifikatsdateien mit ihrem Passwort, die Schnittstellen verwenden. |
| Transaktionen | Die Aufrufe, die über eine Schnittstelle laufen. |
...
Schnittstellen
Die Übersicht
Die Liste zeigt beim Öffnen alle Schnittstellen Ihres Mandanten und die Schnittstellen übergeordneter Mandanten, die für Sie freigegeben sind.
| Spalte | Bedeutung |
|---|---|
| Service-Key | Der eindeutige Schlüssel der Schnittstelle. Transaktionen und Formulare verwenden ihn als Verweis. |
| Aktiv | Ampel: aktiv oder deaktiviert. |
| Service-Typ, Auth-Typ | Art der Schnittstelle und Art der Anmeldung, als Symbol mit Text beim Überfahren. |
| Secrets | Anzahl der hinterlegten Zugangsdaten und Keystores. Ein Klick zeigt, welche es sind, nie ihren Wert. |
| URL | Die Adresse des Drittsystems. |
| Herkunft | «eigen» oder der Name des übergeordneten Mandanten. Der Zusatz «(überdeckt)» bedeutet: Ihr Mandant hat eine eigene Schnittstelle mit demselben Schlüssel, und diese gilt. |
| Freigabe | Symbol, wenn die Schnittstelle für untergeordnete Mandanten freigegeben ist. |
| Letzte Anpassung | Zeitpunkt der letzten Änderung. |
Die Suchmaske filtert nach Service-Key, Service-Typ, Auth-Typ, Aktiv, URL und Beschreibung. Die Spalte «Beschreibung» lässt sich über die Spaltenauswahl einblenden.
...
- In der Übersicht eine neue Schnittstelle anlegen.
- Service-Key, Service-Typ und Auth-Typ wählen. Je nach Auth-Typ erscheinen weitere Felder.
- URL und die Angaben zur Anmeldung ausfüllen.
- Die Zugangsdaten setzen, siehe «Zugangsdaten setzen».
- «Speichern».
| Info | ||
|---|---|---|
| ||
Nach dem ersten Speichern ist die Schnittstelle aktiv. Sie muss deshalb beim ersten Speichern vollständig sein, einschliesslich der Zugangsdaten. |
Felder
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Service-Key | ✔ | 1 bis 128 Zeichen aus Buchstaben, Ziffern, _, - und .. Im Mandanten eindeutig, ohne Rücksicht auf Gross- und Kleinschreibung. Nach dem Anlegen nicht mehr änderbar. |
| Für Untermandanten freigegeben | ❌ | Gibt die Schnittstelle an untergeordnete Mandanten frei. Diese sehen sie schreibgeschützt und können sie verwenden. |
| Service-Typ | ✔ | REST, SOAP, Dateisystem oder LDAP. |
| Auth-Typ | ✔ | Die Art der Anmeldung, siehe nächste Tabelle. |
| URL | ❌ | Adresse des Drittsystems, höchstens 1'024 Zeichen. |
| Transformation | ❌ | Verweis auf eine Transformation, höchstens 512 Zeichen. |
| Beschreibung | ❌ | Freier Text, höchstens 255 Zeichen. |
| Implementation | ❌ | Java-Klasse, Generisch REST oder Generisch SOAP. Ohne Auswahl gilt der Standard des Service-Typs. |
| Java-Klasse | ❌ | Name der Klasse. Erscheint nur bei der Implementation «Java-Klasse». |
| Notiz | ❌ | Interne Notiz zur Schnittstelle. |
| Statische Header | ❌ | Liste aus Name und Wert. Die Header werden bei jedem Aufruf mitgesendet. |
| Properties | ❌ | Liste aus Name und Wert für weitere Einstellungen der Schnittstelle. |
| Client-Keystore, Truststore | ❌ | Im Abschnitt «Keystores», siehe «Keystore zuordnen». |
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
| Auth-Typ | Zusätzliche Felder | Zugangsdaten |
|---|---|---|
| Keine Anmeldung | keine | keine |
| Basic (Benutzer und Passwort) | Benutzername (Pflicht), Token-URL (falls das Drittsystem eine eigene Login-Adresse hat) | Passwort |
| API-Key | Header des API-Keys (Standard X-API-Key) | API-Key |
| Bearer-Token | keine | Bearer-Token |
| OAuth 2.0 Client Credentials | Token-URL und Client-ID (Pflicht), Scope, Anmeldung am Token-Endpoint (Standard BODY), Feld des Access-Tokens (Standard access_token), Feld der Gültigkeit (Standard expires_in) | Client-Secret |
| SOAP (Benutzer und Passwort) | Benutzername (Pflicht) | SOAP-Passwort |
| Signaturschlüssel (Java-Klasse signiert selbst) | Nur mit der Implementation «Java-Klasse» | Signaturschlüssel |
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.
...
- In der Zeile auf das Stift-Symbol «Neuen Wert setzen …» klicken.
- Im Dialog den Wert in «Neuer Wert» und nochmals in «Wert wiederholen» eingeben.
- «Übernehmen». Die Zeile zeigt «neuer Wert gesetzt».
- Die Schnittstelle speichern. Erst jetzt wird der Wert verschlüsselt abgelegt.
| Warnung | ||
|---|---|---|
| ||
Bewahren Sie Zugangsdaten zusätzlich dort auf, wo Ihre Organisation Passwörter verwaltet. In der Schnittstellen-Verwaltung können Sie einen Wert überschreiben, aber nicht mehr anzeigen. Das Auge-Symbol «Anzeigen» steht nur berechtigten Support-Benutzern des Betreibers zur Verfügung; jede Anzeige wird protokolliert. |
...
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.
| Feld | Beschreibung |
|---|---|
| Client-Keystore | Das Zertifikat, mit dem sich die Schnittstelle beim Drittsystem ausweist. |
| Truststore | Die Zertifikate, denen die Schnittstelle vertraut. Ohne Auswahl gelten die Zertifikate des Servers. |
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
| Knopf | Wirkung |
|---|---|
| Speichern | Speichert die Angaben und einen neu gesetzten Wert der Zugangsdaten. |
| Deaktivieren | Die Schnittstelle bleibt gespeichert, wird aber nicht mehr verwendet. Aufrufe über diesen Service-Key schlagen fehl, auch wenn ein übergeordneter Mandant eine Schnittstelle mit demselben Schlüssel freigegeben hat. |
| Aktivieren | Die Schnittstelle wird wieder verwendet. Sie muss dafür vollständig sein. |
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: …».
...
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.
...
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
| Spalte | Bedeutung |
|---|---|
| Name | Der Name des Keystores. |
| Art | Client-Keystore oder Truststore. |
| Typ | Das Format der Datei: PKCS12, JKS oder JCEKS. Es wird aus der Datei erkannt. |
| Ablauf | Das früheste Ablaufdatum der enthaltenen Zertifikate. Orange: läuft in weniger als 30 Tagen ab. Rot: abgelaufen. |
| Verwendet von | Anzahl der Schnittstellen, die den Keystore verwenden. Ein Klick zeigt ihre Service-Keys. |
| Letzte Anpassung, Benutzer letzte Anpassung | Zeitpunkt und Benutzer der letzten Änderung. |
Die Liste zeigt nur die Keystores Ihres Mandanten. Keystores werden nicht an untergeordnete Mandanten weitergegeben.
...
- In der Liste einen neuen Keystore anlegen.
- Name und Art wählen.
- In der Zeile «Datei» auf «Datei und Passwort hochladen …» klicken.
- Im Dialog zuerst die Datei wählen (
.p12,.pfx,.jksoder.jceks, höchstens 1'024 KB), dann das Passwort eingeben. Bei einem Truststore ist das Passwort freiwillig. - Der Dialog prüft die Datei sofort und zeigt ihre Einträge mit Ablaufdatum.
- «Übernehmen».
- Den Keystore speichern. Erst jetzt werden Datei und Passwort verschlüsselt abgelegt.
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Name | ✔ | Höchstens 128 Zeichen, im Mandanten eindeutig. |
| Art | ✔ | Client-Keystore oder Truststore. Nicht mehr änderbar, solange eine Schnittstelle den Keystore verwendet. |
| Beschreibung | ❌ | Freier Text, höchstens 255 Zeichen. |
| Datei | ✔ | Zeigt den Zustand: «keine Datei», Typ und Ablaufdatum der gespeicherten Datei oder «neue Datei: … – wird mit dem Speichern übernommen». |
| Verwendet von | – | Die Service-Keys der Schnittstellen, die den Keystore verwenden. Nur Anzeige. |
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.
| Warnung (Auszug) | Bedeutung |
|---|---|
expires at …, in less than 30 days | Ein Zertifikat läuft bald ab. Besorgen Sie rechtzeitig ein neues. |
expired at … | Ein Zertifikat ist abgelaufen. Das Drittsystem wird die Verbindung ablehnen. |
protected with … | Die Datei ist mit einem veralteten Verfahren geschützt, zum Beispiel im Format JKS. |
key of … bits, at least … | Ein Schlüssel ist kürzer, als heute empfohlen wird. |
Zertifikat erneuern
- Den Keystore öffnen.
- «Datei und Passwort hochladen …» und die neue Datei mit ihrem Passwort angeben.
- Der Dialog nennt, für wie viele und welche Schnittstellen die neue Datei gelten wird.
- «Übernehmen» und den Keystore speichern.
...
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
| Feld | Pflicht | Beschreibung |
|---|---|---|
| Name | ✔ | Der Name, unter dem die Transaktion in Listen und Auswahlen erscheint. |
| Beschreibung | ✔ | Freier Text zum Zweck der Transaktion. |
| Transaktions-Schritte | ✔ | Mindestens ein Schritt. Die Schritte laufen in der Reihenfolge der Liste und lassen sich umsortieren. Ein Schritt kann Unterschritte haben. |
Jeder Schritt hat diese Felder:
| Feld | Pflicht | Beschreibung |
|---|---|---|
| ID | ❌ | Eine Kennung des Schritts. |
| Verhalten im Fehlerfall | ❌ | CONTINUE: Die Transaktion läuft nach einem Fehler dieses Schritts weiter. ROLLBACK: Ein Fehler dieses Schritts bricht die Transaktion ab; bricht sie später ab, wird dieser Schritt rückgängig gemacht, sofern seine Implementation das unterstützt. Ohne Wahl bricht ein Fehler die Transaktion ab. |
| Implementation | ✔ | Die Klasse, die den Schritt ausführt. Die Auswahl zeigt alle verfügbaren Klassen mit ihrem vollständigen Namen. |
| Eigenschaften | ❌ | Liste der Einstellungen des Schritts, siehe unten. |
Eine Eigenschaft besteht aus:
| Feld | Beschreibung |
|---|---|
| Schlüssel | Der Name der Eigenschaft, zum Beispiel path. |
| Statischer Wert | Ein fester Wert. |
| Formel | Eine Formel, die den Wert zur Laufzeit berechnet. Sie hat Vorrang vor dem statischen Wert. |
| Typ | Der Datentyp als Java-Klasse, Standard ist java.lang.String (Text). Für Zahlen und Ja/Nein-Werte den passenden Typ wählen. |
| Referenzierte Eigenschaft | Verweis auf eine vordefinierte Eigenschaft einer Klasse. |
REST-Aufruf über eine Schnittstelle
Für einen REST-Aufruf besteht die Transaktion aus einem Rahmen und einem oder mehreren Unterschritten:
| Schritt | Implementation | Aufgabe |
|---|---|---|
| Rahmen | SequentialGenericRESTHandler | Stellt die Verbindung zur Schnittstelle her. |
| Unterschritt | GenericRESTJsonStepCommand | Ein Aufruf mit einer JSON-Antwort. |
| Unterschritt | GenericRESTJsonArrayStepCommand | Ein Aufruf, dessen Antwort eine JSON-Liste ist. |
| Unterschritt | GenericRESTMultipartStepCommand | Ein Aufruf, der eine Datei hochlädt. |
Der Rahmen verweist mit der Eigenschaft serviceId auf die Schnittstelle. Ihr Wert ist der Service-Key.
...
Eigenschaften eines REST-Unterschritts
| Schlüssel | Standard | Beschreibung |
|---|---|---|
path | – | Wird an die URL der Schnittstelle angehängt. Platzhalter: ${xpath:/…} für einen Wert aus dem Formular, ${NAME} für eine Variable. |
httpMethod | POST | GET, POST, PUT, PATCH oder DELETE. |
queryParams, headers | – | Zusätzliche Parameter und Header als JSON-Objekt aus Name und Wert. Keine Zugangsdaten. |
transformOut, transformIn | – | Mapping vom Formular in die Anfrage bzw. von der Antwort ins Formular. |
requestContentType | application/json | Format der Anfrage. |
responseType | json | json, jsonarray oder text. |
expectedResponseCodes | 200 | Erwartete Statuscodes, zum Beispiel 200,201, 2xx oder 200-204. Jeder andere Code gilt als Fehler. |
retryCount, retryBackoffMillis | 0, 500 | Anzahl der Wiederholungen und Wartezeit dazwischen. |
connectTimeoutMillis, readTimeoutMillis | 10 und 30 Sekunden | Zeitlimiten für Verbindungsaufbau und Antwort. |
mode | normal | simulation: Die Anfrage wird vorbereitet und protokolliert, aber nicht gesendet. logging: Anfrage und Antwort werden protokolliert. Zugangsdaten stehen nie im Protokoll. |
| Warnung | ||
|---|---|---|
| ||
Die Eigenschaften |
Weitere Arten von Schritten
| Art | Implementation (Auswahl) | Hinweis |
|---|---|---|
| Generisch SOAP | Rahmen SequentialGenericWSDLHandler, Schritt GenericSOAPStepCommand | Verwendet keine Schnittstelle, sondern die Eigenschaft wsdlUrl, ohne Anmeldung. |
| Formulardaten | FormdataJSONTransactionStep, FormdataAttachmentsTransactionStep | Stellt die Daten und Beilagen des Formulars bereit. |
| Geschäftsverwaltung CMI | zum Beispiel CreateGeschaeft, FindGeschaeft, CreateOrUpdatePDF | Enthält der Name der Transaktion «CMI», wird sie als CMI-Export ausgeführt. |
| Initialisierung | InitSkribbleAPI, InitDeepSignAPI, InitHisoftApi, InitInnosolvApi | Bereitet die Verbindung zu einem bestimmten Dienst vor. |
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.
...
Die Zugangsdaten beim Anbieter prüfen und neu setzen. Bei einem Client-Zertifikat das Ablaufdatum in der Liste «Keystores» kontrollieren.
...
- 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