Anbinden und testen
Die Anbindung eines externen Registers im Studio eintragen und testen.
Studio-Rollen: „Eigentümer“, „Administrator“, „Community-Manager“.
Das Register anlegen
Im Studio legt unter „Register“ die Schaltfläche „Neues Register“ das Register mit der Art „Extern“ an. Die Art steht fest, sobald das Register existiert. Die Gruppen des Registers werden einmal für alle festgelegt, die darin gefunden werden.
Die Anbindung eintragen
Auf der Karte „Anbindung“ des Registers:
| Feld | Was eintragen |
|---|---|
| „Basis-URL“ | Die Basis-URL Ihres Registers. Beginnt mit https://; einfaches http nur für localhost oder 127.0.0.1, für ein lokales Testregister |
| „Mandanten-ID“ | Wird als Header x-tenant-id gesendet. Stimmen Sie den Wert mit dem Betreiber des Registers ab |
| „Scope“ | Wird als Header x-custom-scope gesendet |
| „Prüfcode erforderlich“ | Einschalten, wenn beim Onboarding der Prüfcode der Person abgefragt wird; das Studio ruft dann „Ein Mitglied mit seinem Prüfcode verifizieren“ auf |
Dann „Anbindung speichern“. „Mandanten-ID“ und „Scope“ nehmen nur druckbares ASCII, jeweils höchstens 255 Zeichen, weil sie als HTTP-Header gesendet werden.
Der API-Schlüssel wird eigens gesetzt, mit „API-Schlüssel setzen“ und später „API-Schlüssel ersetzen“. Er wird als Header x-api-key gesendet, verschlüsselt gespeichert und kann nie wieder angezeigt, nur ersetzt werden. Der neue Schlüssel gilt sofort, und die Registeraktivität vermerkt, dass der Schlüssel geändert wurde, nie den Schlüssel selbst.
Wenn Sie Schema, Host oder Port der Basis-URL ändern, wird der API-Schlüssel entfernt: Die neue Adresse erhält den alten Schlüssel nicht. Setzen Sie den Schlüssel danach erneut.
Die Verbindung testen
„Verbindung testen“ öffnet den Dialog „Verbindung testen“. Geben Sie eine „Test-Mitgliedsnummer (optional)“ ein und klicken Sie auf „Test starten“. Das Studio
- fragt das Register, ob es antwortet (Health-Check);
- sucht die Test-Mitgliedsnummer, wenn Sie eine eingegeben haben (Die Personendaten eines Mitglieds), und zeigt die zurückgegebenen Personendaten, die es nicht speichert;
- prüft, ob das Register „Alle Mitglieder auflisten“ unterstützt.
Die Karte zeigt die Verbindung dann als „Verbunden“ oder „Nicht erreichbar“, mit dem Zeitpunkt des letzten Tests. Ein fehlgeschlagener Test nennt die Ursache, zum Beispiel:
| Das Studio sagt | Meistens |
|---|---|
| „keine Antwort innerhalb von 5 Sekunden“ | Das Register ist langsam oder nicht erreichbar |
| „die Adresse ist nicht erlaubt (private oder reservierte Adresse)“ | Die Basis-URL zeigt in ein privates Netz |
| „Zugangsdaten abgelehnt (HTTP 401)“ | API-Schlüssel oder Mandanten-ID sind falsch |
| „die Antwort entspricht nicht dem API-Vertrag“ | Ein Feld hat den falschen Typ; die genannten Pfade zeigen, welches |
| „gefunden, aber ohne Personendaten“ | Der Antwort fehlen Vorname, Nachname oder Geburtsdatum |
| „das Register meldet sich als nicht betriebsbereit“ | Der Health-Check hat mit ok: false geantwortet |
Sobald der Test besteht, nehmen Sie das Register in die Mitgliedschaftsdefinition auf. Das erklärt das Studio-Handbuch.