Verbundene Systeme

Ein verbundenes System ist eine andere Software, die eigenständig mit Ihrem Workspace arbeitet: ein ERP, ein Data Warehouse, ein nächtlicher Job. Es meldet sich mit eigenen Zugangsdaten an statt mit dem Konto einer Person, schreibt Daten in einen Datensatz, startet einen Lauf und holt sich die Ergebnisse nach seinem eigenen Zeitplan. Es sitzt niemand an der Tastatur, und es ist kein Browser beteiligt - genau darum geht es. Die Arbeit passiert um drei Uhr nachts, ob jemand da ist oder nicht.

Was ein verbundenes System tun kann

Ein verbundenes System arbeitet über die Automation API, und was es dort darf, entscheidet allein der Zugriff, den Sie seinen Zugangsdaten geben:

• Den Workspace lesen - die Apps auflisten, die Datensätze, in die es schreiben darf, und die Ausgaben, die es lesen darf.
• Daten schreiben - Zeilen in einen Datensatz einer Analyse-App importieren, als Datei, die es hochlädt und der Workspace einliest.
• Eine Pipeline ausführen - einen Lauf starten und ihn bis zum Ende abfragen.
• Ergebnisse lesen - einen Export einer Ausgabe erzeugen und die Datei herunterladen.

Mehr gibt es nicht. Welchen Zugriff Sie auch erteilen: Ein verbundenes System kann keine Apps anlegen oder löschen, keine Pipeline ändern, keine Visualisierung bearbeiten, niemanden einladen und keine Workspace-Einstellungen ändern. Das bleibt bei den Menschen im Workspace.

Wo die Zugangsdaten liegen

Öffnen Sie die Seite Zugriff und dort den Tab API-Zugangsdaten. Zugangsdaten sind wie ein Mitglied ein Prinzipal des Workspace und werden deshalb neben den Mitgliedern verwaltet: Wer und was hier arbeiten darf, steht auf einer Seite. Der Tab ist für Personen, die die API-Zugangsdaten des Workspace verwalten dürfen, und das sind heute die Admins: Einem Mitglied wird er gar nicht angeboten, und jede Anfrage dahinter wird ohne diese Berechtigung abgelehnt.

Jede Zugangsdaten sind eine Zeile in der Tabelle des Tabs: ihr Name, ihr Schlüssel, ihre Zugriffsoptionen, wann sie zuletzt verwendet wurden und wann sie ablaufen oder als Nächstes bestätigt werden müssen. Das Zahnrad einer Zeile öffnet die Details der Zugangsdaten, und das Menü der Zeile bietet Bestätigen, Zugriff bearbeiten, Secret erneuern und Widerrufen. Den Schlüssel kopieren Sie mit der Schaltfläche daneben.

Die Details haben drei Tabs: Details, Zugriff und Aktivität. Zugriff listet jede Berechtigung, die ihre Zugriffsoptionen geben - App-Konfiguration lesen, Daten lesen, Dateien importieren, Pipelines ausführen, Daten herunterladen, veröffentlichen - und welche Option sie jeweils gibt, genauso wie der Zugriff eines Mitglieds gezeigt wird. Zugangsdaten haben keine Rolle: Sie wirken in jedem gemeinsamen Bereich und jeder App darin, auch in später angelegten Apps, und nie im persönlichen Bereich einer Person. Widerrufene Zugangsdaten können nichts mehr.

Zugangsdaten gehören dem Workspace, nicht einer Person - sie funktionieren weiter, wenn die erstellende Person den Workspace verlässt. Die Liste nennt weiterhin die Person, die sie ausgestellt hat, und markiert die Zugangsdaten mit Ehemaliges Mitglied, sobald diese Person nicht mehr im Workspace ist. So haben Sie einen Anlass zu prüfen, ob die Integration noch gewollt ist.

Tour der API-Zugangsdaten starten, um sich Zugangsdaten zeigen zu lassen, was das Erneuern und das Widerrufen jeweils kosten, und das Formular, das neue Zugangsdaten ausstellt. Die Tour legt nie Zugangsdaten an - sie hält bei der Schaltfläche an und wartet auf Sie.

Zugangsdaten ausstellen

Neue Zugangsdaten fragt nach einem Namen, einer optionalen Beschreibung und dem Zugriff, den Sie erteilen. Benennen Sie sie nach dem System, für das sie sind ("ERP-Nachtimport" statt "Test"), denn dieser Name erscheint im Prüfprotokoll des Workspace, sobald die Integration etwas schreibt.

Beim Erstellen entstehen zwei Zeichenketten:

• eine Client-ID, die die Zugangsdaten identifiziert und gefahrlos angezeigt werden darf, und
• ein Client-Secret, mit dem das System nachweist, dass es diese Zugangsdaten besitzt.

Das Secret wird genau einmal angezeigt. Es steht in dem Dialog, der direkt nach dem Erstellen erscheint, und nichts kann es erneut anzeigen: Es ist nirgends so gespeichert, dass jemand es zurücklesen könnte, auch kein Admin. Geht es verloren, erneuern Sie das Secret - dabei wird ein neues ausgestellt. Der Dialog kopiert beide einzeln oder zusammen als Umgebungsvariablen FACTOPHANT_CLIENT_ID und FACTOPHANT_CLIENT_SECRET, und Ich habe es gespeichert schließt ihn und verwirft das Secret von der Seite.

Geben Sie beides an die Person weiter, die die Integration baut. Alles Weitere - wie sich das System damit anmeldet, welche Endpunkte es aufruft, wie die Datei aussehen muss - ist die Entwicklerseite der Arbeit und steht im maschinenlesbaren Vertrag der API selbst, nicht in dieser Anleitung.

Was die Zugriffsoptionen bedeuten

Jede Option erteilt genau eine Art von Arbeit und sonst nichts. Neben der Beschriftung zeigt die Auswahl außerdem den technischen Namen, den die Option in der API trägt - nach diesem Namen fragt die Person, die die Integration baut:

Zwei Kennzeichen in der Auswahl sagen Ihnen, wie diese Liste zu lesen ist:

• Erweitert markiert eine Option, die über das Lesen und das Ausführen der veröffentlichten Konfiguration hinausgeht - etwa einen Entwurf auszuführen, den noch niemand geprüft hat, oder zu veröffentlichen und damit zu ändern, was alle im Workspace sehen. Eine erweiterte Option ist eine bewusste Einzelentscheidung für eine bestimmte Integration und nichts, was neue Zugangsdaten einfach mitbringen. Erteilen Sie sie nur, wenn das System sie wirklich braucht.
• Noch ohne Wirkung markiert eine Berechtigung, die derzeit nirgends geprüft wird. Sie gehört zum Vokabular, lässt sich also erteilen, speichern und anzeigen, aber sie zu erteilen ändert nichts, was ein Admin beobachten könnte. Das Kennzeichen ist die ehrliche Antwort auf die Frage, was eine Option heute tatsächlich bewirkt, und es verschwindet, sobald die Option zu wirken beginnt.

Zugriff bearbeiten ändert die Berechtigungen bestehender Zugangsdaten. Es muss nichts neu ausgestellt werden: Die Änderung gilt ab der nächsten Anfrage dieser Zugangsdaten, und ein Entzug wirkt auch auf ein bereits ausgestelltes Token.

Das Secret erneuern

Secret erneuern stellt ein neues Secret aus, ohne dass etwas ausfällt. Das heute verwendete Secret funktioniert neben dem neuen noch 24 Stunden weiter, Sie können das neue also ausrollen statt unter Zeitdruck, und hört dann von selbst auf - nie später als zu dem Datum, an dem die Zugangsdaten ohnehin abgelaufen wären. Die Details zeigen, wann das vorherige Secret ungültig wird und wann es zuletzt verwendet wurde - so sehen Sie es verstummen. Jetzt zurückziehen daneben akzeptiert es sofort nicht mehr, zusammen mit jedem damit ausgestellten Token.

Mehr als zwei Secrets gibt es nie: Erneuern Sie erneut, solange ein altes Secret noch funktioniert, wird dieses sofort verworfen, und der Dialog sagt das vor dem Bestätigen.

Die Antwort auf ein offengelegtes Secret ist "erneuern und sofort zurückziehen". Erneuern Sie die Zugangsdaten und wählen Sie im Dialog Dieses Secret ist möglicherweise offengelegt: sofort nicht mehr akzeptieren: Das alte Secret und jedes damit ausgestellte Token sind mit dem Bestätigen sofort ungültig, und nur das neue Secret funktioniert. Haben Sie bereits mit der Voreinstellung erneuert, nutzen Sie stattdessen Jetzt zurückziehen in den Details der Zugangsdaten. Auch wer abgelaufene oder gesperrte Zugangsdaten erneuert, behält keine Übergangszeit: Das alte Secret konnte sich nicht anmelden, danach funktioniert nur das neue.

Erneuern Sie außerdem, wenn die Person geht, die die Integration eingerichtet hat, oder in dem Rhythmus, den Ihre eigene Richtlinie vorgibt.

Erkennen, ob es funktioniert

Zwei Stellen geben Auskunft, jede auf eine andere Frage:

• Die Tabelle der Zugangsdaten sagt, ob die Zugangsdaten überhaupt verwendet werden. Zuletzt verwendet ist der Zeitpunkt der letzten Anmeldung und steht auf "Nie verwendet", bis der erste erfolgreiche Aufruf der Integration eingegangen ist - das ist deshalb das Erste, was man bei einer neuen, stummen Integration prüft.
• Das Prüfprotokoll sagt, was das System tatsächlich getan hat. Alles, was ein verbundenes System tut, wird wie jede andere Änderung aufgezeichnet: Öffnen Sie die App Audit Analytics, gehen Sie auf All actions (Alle Aktionen) und filtern Sie die Akteur-Art auf Integration. Der Akteur einer maschinellen Schreiboperation ist die Integration selbst, unter dem Namen ihrer Zugangsdaten - nicht der Admin, der die Zugangsdaten ausgestellt hat, denn er hat die Maschine autorisiert, die Aktion aber nicht ausgeführt. Wie man das Protokoll liest, steht auf der Seite Prüfprotokoll.

Die Ereignisse zu den Zugangsdaten selbst - erstellt, Secret erneuert, Zugriff geändert, widerrufen - stehen im selben Protokoll und sind dem Admin zugeschrieben, der sie ausgeführt hat, denn dort hat tatsächlich eine Person gehandelt.

Widerrufen

Widerrufen setzt Zugangsdaten sofort außer Kraft, auch bereits ausgestellte Token: Die nächste Anfrage wird abgelehnt. Das lässt sich nicht rückgängig machen - den Zugriff wiederherzustellen heißt, neue Zugangsdaten auszustellen und dem System das neue Secret zu geben.

Widerrufene Zugangsdaten bleiben in der Liste, markiert mit Widerrufen und mit nichts mehr zu ändern, nur ihr Schlüssel lässt sich noch kopieren, und sie behalten ihren Namen im Prüfprotokoll - so bleibt lesbar, was sie getan haben, solange sie gültig waren.