Entwerfe ein Integrationsverzeichnis, das von 3 auf 30 Integrationen skaliert: einfaches Datenmodell, klare Status, Berechtigungen und UI für Setup‑Fortschritt.
Nutzer öffnen ein Integrationsverzeichnis aus einem Grund: um Tools zu verbinden und sie ohne tägliches Nachdenken laufen zu lassen. Wenn die Seite raten lässt, was verbunden ist, was kaputt ist oder was als Nächstes zu tun ist, schwindet das Vertrauen schnell.
Bei 3 Integrationen reicht oft ein einfaches Logo‑Grid. Bei 30 bricht das auseinander: Leute hören auf zu scannen, Support‑Tickets steigen und der „Connect“-Button wird zur Falle, weil jede Integration in einem anderen Zustand sein kann.
Jede Integrationskarte (oder Zeile) sollte auf einen Blick drei Fragen beantworten:
Die meiste Verwirrung entsteht durch Randfälle, die in echten Teams ständig vorkommen. Jemand verbindet Google mit einem persönlichen Konto statt dem Firmenkonto. Ein Stripe‑Token läuft ab und die Abrechnung synchronisiert nicht mehr. Ein Slack‑Workspace ist verbunden, aber der benötigte Channel‑Scope wurde nie gewährt, sodass das Setup „halb fertig“ ist, obwohl die UI normal aussieht.
Eine gute Seite macht diese Situationen offensichtlich. Statt nur „Connected“ zeige etwas wie „Connected (benötigt Berechtigung)“ oder „Connected to: [email protected]“ und platziere den nächsten Schritt direkt auf der Karte. Das verhindert Raten und hält die Liste auch bei Wachstum übersichtlich.
Der einfachste Weg, ein Integrationsverzeichnis skalierbar zu machen, ist die Trennung von:
Das bleibt bei 3 Integrationen lesbar und funktioniert auch bei 30.
Eine Integration ist der Katalogeintrag. Sie ist global und nicht an einen Workspace gebunden.
Eine Install (Installation) repräsentiert, dass ein Workspace diese Integration aktiviert hat (zum Beispiel: „Slack ist für Workspace A eingeschaltet“).
Eine Connection stellt ein tatsächliches externes Konto oder Credential dar (zum Beispiel: „Slack‑Workspace X via OAuth“ oder „Stripe‑Account Y via API‑Key“). Eine Install kann mehrere Connections haben.
Ein minimales Set von Feldern, das sich bewährt:
Speichere für Nutzer sichtbare Konfiguration (ausgewählter Channel, Webhook‑URL‑Kurzname, aktivierte Events) in Install oder Connection als normale Daten. Secrets (OAuth‑Refresh‑Tokens, API‑Keys, Signing‑Secrets) gehören nur in einen Secret‑Store oder verschlüsselte Felder mit strengen Zugriffskontrollen.
Gib keine Secrets, vollständige Autorisierungscodes oder rohe Webhook‑Payloads in Logs aus. Wenn du etwas loggen musst, logge Referenzen (connection_id) und sichere Metadaten (HTTP‑Status, Fehlercode).
Um flexibel über OAuth, API‑Keys und Webhooks zu bleiben, halte auth‑spezifische Felder in Connection (Token‑Metadaten vs Key‑Fingerprint vs Webhook‑Verifizierungsstatus). UI‑sichtbaren Zustand (enabled und Setup‑Fortschritt) halte auf Install.
Nutzer öffnen ein Integrationsverzeichnis, um drei Dinge schnell zu beantworten: funktioniert es, wie weit ist das Setup, und was soll ich als Nächstes tun. Wenn Statusbegriffe vage sind, steigen Support‑Anfragen und das Vertrauen sinkt.
Beginne mit einer kleinen Statusmenge, die du jahrelang halten kannst:
Bevorzuge abgeleitete Status gegenüber gespeicherten Labels. Gespeicherte Labels verwittern: Jemand behebt einen Fehler, aber das Badge bleibt rot. Abgeleiteter Status wird aus Fakten berechnet, die du ohnehin trackst, z. B. ob Tokens gültig sind, ob erforderliche Setup‑Schritte erledigt sind und ob ein Admin die Integration pausiert hat. Wenn du etwas speicherst, speichere die zugrundeliegenden Fakten (letzter erfolgreicher Sync, letzter Fehlercode), nicht das finale Label.
Setup‑Fortschritt funktioniert am besten als kurze Checkliste mit klarer Trennung zwischen Pflicht und Optional. Modelle es als Schrittdefinitionen (statisch, pro Integration) plus Schrittresultate (pro Install).
Beispiel: Slack könnte „Workspace autorisieren“ und „Channels auswählen“ als Pflichtschritte haben, mit einem optionalen Schritt wie „Message‑Previews aktivieren“. Die UI kann „2 von 3 erforderlichen Schritten abgeschlossen“ anzeigen und gleichzeitig optionale Elemente sichtbar, aber nicht blockierend halten.
Mehrere Connections unter einer Integration können ein Verzeichnis unübersichtlich machen, wenn du das nicht planst. Halte eine Karte pro Integration, zeige die Anzahl der Connections und fasse den Status ehrlich zusammen. Wenn irgendeine Connection defekt ist, zeige „Needs attention“ mit einem Hinweis wie „1 von 4 Workspaces benötigt Re‑Auth“. Die Übersicht bleibt sauber, spiegelt aber die Realität wider.
Integrationsberechtigungen werden kompliziert, wenn alles als ein Schalter behandelt wird. Es ist klarer, zu trennen:
Beginne mit einer leichten Rollenprüfung, die überall gilt. Für viele Apps reichen drei Rollen: Admin, Manager und Member. Admins dürfen alles. Manager können die meisten Integrationen für ihr Team einrichten. Members können bereits aktivierte Integrationen benutzen, dürfen jedoch keine Einstellungen ändern.
Füge dann pro Integration nur dort zusätzliche Flags ein, wo sie wirklich nötig sind. Die meisten Integrationen (Kalender, Chat) können Standardrollen folgen. Sensible Integrationen (Zahlungen, Payroll, Exporte) sollten eine zusätzliche Prüfung wie „Payments admin“ oder „Billing manager“ verlangen. Halte das als einfaches Boolean‑Flag auf der Install, nicht als komplettes neues Rollensystem.
Eine lesbare Zuordnung könnte so aussehen:
Audit muss nicht schwergewichtig sein, aber vorhanden. Erfasse genug, um Support‑ und Sicherheitsfragen schnell zu beantworten: wer hat verbunden, wann wurden Credentials geändert und wer hat deaktiviert. Ein „Activity“-Panel auf der Detailseite mit 5–20 jüngeren Events reicht meist aus.
Beispiel: Stripe könnte für alle sichtbar sein, aber nur Admins (oder Nutzer mit „Billing manager“) dürfen verbinden, Keys rotieren oder Auszahlungen deaktivieren. Slack könnte Managern erlauben zu verbinden, während Members weiterhin Slack‑Benachrichtigungen erhalten, sobald es aktiviert ist.
Bei 3 Integrationen kannst du alles zeigen. Bei 30 muss das Verzeichnis schnell beantworten: „Welche funktionieren, und was mache ich als Nächstes?“ Die sauberste Herangehensweise ist, Scannen und Handeln zu trennen.
Halte die Verzeichnisansicht auf schnelle Entscheidungen fokussiert. Schiebe schwerere Steuerungen auf eine Detailseite hinter einem einzigen „Manage“-Button.
In der Liste zeige nur das, was den nächsten Klick unterstützt:
Die Anatomie der Karte ist wichtig, weil sie Muskelgedächtnis aufbaut. Die primäre Aktion sollte immer „der nächste Schritt“ bedeuten: Connect für neu, Continue setup für teilweise eingerichtet, Reconnect bei abgelaufener Auth und Manage, wenn alles gesund ist. Vermeide zwei gleich laute Buttons pro Karte — das macht die Seite laut und unruhig.
Beispiele:
Leere Zustände sollten anleiten, ohne eine Bedienungsanleitung herunterzuladen:
So bleibt die Seite bei 30 Integrationen ruhig, weil jede Karte beantwortet: was ist es, ist es okay, und was mache ich jetzt?
Die Verzeichnisliste bringt Nutzer zur richtigen Integration. Auf der Detailseite entscheiden sie: einrichten, reparieren oder abschalten. Halte die Seitenstruktur über alle Integrationen konsistent, auch wenn die Backend‑Arbeit unterschiedlich ist.
Beginne mit einer kompakten Übersicht: Integrationsname, einzeilige Beschreibung und klare Statuslabels (Connected, Needs attention, Disabled). Füge eine kleine „Setup‑Progress“-Zeile hinzu, damit Nutzer wissen, ob sie kurz vor dem Abschluss stehen oder noch am Anfang sind.
Ein einfacher Wizard funktioniert gut: 3–6 Schritte, ein Bildschirm pro Schritt, mit immer verfügbarem „Zurück“. Benenne Schritte in klarer Sprache (Konto verbinden, Workspace auswählen, Zu synchronisierende Daten auswählen, Bestätigen). Wenn ein Schritt optionale Wahlmöglichkeiten hat, markiere sie als optional, statt sie zu verstecken.
Wenn das Setup pausierbar ist, sag das deutlich: „Du kannst später fertigstellen. Wir merken uns deine Auswahl.“ Das reduziert die Angst vor dem Verlassen des Flows.
Zeige Connections in einer kleinen Tabelle: Kontoname, verbunden von (User), Erstellungsdatum und letzter Sync.
Beim „nächsten Sync“ vermeide genaue Versprechen, die du nicht halten kannst. Formulierungen wie „Nächster Sync: in Kürze geplant“ oder „Nächster Sync: innerhalb der nächsten Stunde“ sind besser, wenn sie deinem System entsprechen.
Gefährliche Aktionen sollten nicht im Hauptpfad liegen. Platziere primäre Aktionen oben (Continue setup, Reconnect). Stelle Disable und Disconnect in einen separaten „Danger zone“-Bereich am Ende mit kurzer Erklärung der Auswirkungen. Wenn du Rollen unterstützt, erwähne es in einem Satz (z. B. „Nur Admins können trennen“).
Füge ein kleines Aktivitätsprotokoll hinzu: jüngste Events (connected, token refreshed, sync failed), Zeitstempel und eine kurze Fehlermeldung, die Nutzer in ein Support‑Ticket kopieren können.
Eine Integration hinzuzufügen ist einfacher, wenn du sie wie ein kleines Produkt behandelst. Sie braucht einen Eintrag im Katalog, eine Verbindungs‑Möglichkeit, einen Ort zum Speichern der Connection und klare Ergebnisse für Erfolg oder Fehler.
Füge die Integration zum Katalog hinzu, damit sie im Verzeichnis erscheint, bevor sie jemand verbindet. Inkludiere klaren Namen, kurze Beschreibung, Icon und ein oder zwei Kategorien (Messaging, Payments). Beschreibe in einfachen Worten, was das Setup erfordert, z. B. „Konto verbinden“ und „Workspace wählen“. Definiere hier auch später benötigte Dinge (OAuth‑Scopes, erforderliche Felder, unterstützte Features).
Wähle die einfachste passende Verbindung für den Provider:
Wenn der Nutzer den Flow abschließt, erstelle ein Connection‑Record, das an Workspace oder Account gebunden ist, nicht nur an den Nutzer. Speichere Credentials sicher (verschlüsselt at rest und zeige das Secret nicht wieder vollständig). Speichere die Basics, die du für Support brauchst: Provider‑Account‑ID, Erstellungszeit, wer verbunden hat und welche Berechtigungen gewährt wurden.
Führe sofort einen einfachen Test aus (bei Stripe: Account‑Details abrufen). Besteht der Test, zeige Connected und markiere das Setup als abgeschlossen. Besteht der Test teilweise (verbunden, aber Berechtigung fehlt), markiere Needs attention und verlinke zur genauen Behebung.
Zeige eine klare Nachricht, eine empfohlene Aktion und eine sichere Fallback‑Option. Beispiel: „Wir konnten Stripe nicht erreichen. Überprüfe den API‑Key oder versuche es erneut.“ Halte das Verzeichnis nutzbar, auch wenn eine Integration kaputt ist.
Wenn du auf Koder.ai (koder.ai) aufbaust, kannst du zuerst den Katalog, den Setup‑Flow und die Statusregeln in Planning Mode entwerfen und dann UI und Backend aus diesem Plan generieren.
Integrationen scheitern aus langweiligen Gründen. Wenn dein Verzeichnis diese Gründe nicht klar erklären kann, geben Nutzer deiner App die Schuld und Support hat keine Grundlage zum Helfen.
Fasse Fehler in Kategorien zusammen, die zu konkreten Lösungen passen: Login abgelaufen, fehlende Berechtigung, Provider‑Ausfall oder Rate Limit. Behalte interne Fehlercodes detailliert, aber zeige Nutzern ein kurzes, verständliches Label.
Wenn etwas kaputtgeht, sollte die Meldung drei Dinge beantworten: was passiert ist, was der Nutzer tun soll und was dein System als Nächstes macht. Beispiel: „Slack‑Verbindung abgelaufen. Verbinde erneut, um die Synchronisation fortzusetzen. Wir versuchen es nach dem Reconnect automatisch wieder.“ Das ist ruhiger und handlungsorientierter als ein roher API‑Fehler.
Automatische Wiederholungen nur für Probleme, die der Nutzer nicht beheben kann. Eine einfache Regel genügt:
Status können veralten, wenn du sie nicht aktualisierst. Füge einen leichten Health‑Check‑Job hinzu, der regelmäßig Tokens prüft, den letzten Sync verifiziert und bestätigt, dass das Verzeichnis‑Badge der Realität entspricht.
Bewahre pro Install eine kleine Ereignishistorie. Du brauchst keine vollständigen Logs, nur Breadcrumbs: Zeitstempel, Event („token refreshed“, „sync failed“), kurze Begründung und wer es ausgelöst hat (Nutzer oder System). Füge ein intern sichtbares Notizfeld hinzu, damit Support dokumentieren kann, was geändert wurde und warum.
Sobald die Anzahl der Apps steigt, wird das Verzeichnis schnell unübersichtlich. Ziel: Nutzer in Sekunden finden, was sie brauchen, und Probleme ohne Öffnen jeder Karte erkennen.
Beginne mit einfacher Suche über Integrationsname und Kategorie. Die meisten Nutzer tippen, was sie bereits kennen („Slack“, „Stripe“), daher ist Namensmatch wichtiger als kompliziertes Ranking. Kategoriesuche hilft, wenn sie nur die Aufgabe kennen (Payments, Messaging).
Filter sollten reale Absichten widerspiegeln. Diese drei decken die meisten Fälle ab:
Für die Organisation der Liste wähle eine primäre Gruppierung und bleibe dabei. Kategorien funktionieren gut bei hoher Anzahl (CRM, Payments, Messaging). Beliebtheit kann nützlich sein, aber nur, wenn sie deine Nutzerbasis widerspiegelt, nicht das Marketing. Praktische Standardeinstellung: meistgenutzte zuerst, den Rest nach Kategorie gruppiert.
Zeige nicht allen alles. Wenn eine Integration hinter einem Feature‑Flag oder Tarif steckt, blende sie für die meisten Nutzer aus oder zeige sie deaktiviert mit kurzem Grund wie „Business‑Plan“. Vermeide eine Seite voller ausgegrauter Karten — das wirkt kaputt.
Halte die Performance flüssig, indem du Liste und Details separat lädst. Pagiere oder virtualisiere die Liste, damit du nicht 30 schwere Karten gleichzeitig renderst, und lade Details nur, wenn eine Integration geöffnet wird. Die Übersicht zeigt nur Zusammenfassungsfelder (Slack: Connected, Google: Needs attention, Stripe: Not set up), während die Detailseite die vollständige Verbindungs‑Historie lädt.
Stell dir ein Team‑Workspace‑Tool namens Pinework vor. Es hat zwei Rollen: Admin und Member. Admins können Tools verbinden und Einstellungen ändern. Members können verbundene Tools nutzen, aber nicht hinzufügen oder entfernen.
Im Pinework‑Integrationsverzeichnis zeigt jede Karte ein klares Label (Connected, Needs setup, Error), eine kurze „was es tut“‑Zeile und Setup‑Fortschritt wie „2 von 3 Schritten“. So erkennen Nutzer, was funktioniert und was fehlt, ohne herumzuklicken.
Slack wird für Benachrichtigungen verwendet. Ein Admin öffnet Slack und sieht: Status: Connected, Setup: „3 von 3 Schritten“. Members sehen Slack auch, aber die Hauptaktion ist deaktiviert und lautet „Frag einen Admin, um zu verwalten“. Wenn Slack sich trennt, sehen Members, was gebrochen ist, haben aber keinen Zugriff auf Reconnect‑Kontrollen.
Google wird für Kalender genutzt. Pinework erlaubt mehrere Connections. Die Google‑Karte zeigt: Status: Connected (2 Accounts). Darunter listet eine kurze Zeile „Marketing Calendar“ und „Support Calendar“. Das Setup kann komplett sein; die Detailseite zeigt die zwei separaten Connections, damit ein Admin nur eine davon widerrufen kann.
Stripe wird für Abrechnung genutzt. Ein häufiges partielles Setup ist: Account verbunden, Webhooks aber nicht fertig. Die Karte zeigt: Status: Needs setup, Fortschritt: „2 von 3 Schritten“ mit einem Hinweis „Zahlungen werden möglicherweise nicht synchronisiert“. Die Detailseite macht den fehlenden Schritt explizit:
So vermeidest du das frustrierende „es sieht verbunden aus, aber nichts funktioniert“‑Szenario.
Ein Verzeichnis gerät meist nicht wegen „großer Technik“ aus dem Ruder, sondern durch kleine Modellierungs‑ und Labeling‑Fehler, die Nutzer täglich verwirren.
Ein typisches Problem ist die Verwechslung von „installed“ vs „connected“. Installed bedeutet meist „im Workspace verfügbar“, während Connected echte Credentials und Datenfluss bedeutet. Wenn das verschwimmt, klicken Nutzer eine Integration an, die bereit aussieht, und stoßen auf eine Sackgasse.
Ein anderer Fehler ist, zu viele Status‑Zustände zu erfinden. Teams starten mit einem einfachen Badge und fügen dann Randfälle hinzu: pending, verifying, partial, paused, degraded, blocked, expiring und mehr. Mit der Zeit driften diese Labels, weil niemand sie konsistent pflegt. Halte eine kleine Menge, die du mit Prüfungen belegen kannst, wie Not connected, Connected, Needs attention.
Versteckte Berechtigungen sind ebenfalls problematisch. Jemand verbindet ein Konto und entdeckt später, dass die Integration weitergehenden Zugriff hatte als erwartet. Mache die Scopes vor dem finalen „Connect“-Schritt deutlich und zeige sie erneut auf der Detailseite, damit Admins auditieren können.
Viele Apps brauchen mehrere Connections: zwei Slack‑Workspaces, mehrere Stripe‑Accounts oder ein geteiltes Google‑Konto plus persönliche Konten. Wenn du „eine Integration = eine Connection“ hartkodierst, entstehen später hässliche Workarounds.
Plane für:
Halte die Listenansicht leicht. Wenn du sie mit Logs, Feldzuordnungen und langen Beschreibungen vollstopfst, verlangsamt das Scannen. Nutze die Liste für Name, kurzen Zweck und Setup‑Fortschritt. Lege Historie und erweiterte Einstellungen auf die Detailseite.
Ein skalierbares Integrationsverzeichnis beruht auf einem einfachen Modell und einer ehrlichen UI. Wenn Nutzer drei Fragen schnell beantworten können, wirkt das System vorhersehbar: was ist verbunden, was ist kaputt und was soll ich als Nächstes tun?
Checkliste vor dem Launch:
Als Nächstes wähle drei Integrationen, die du gut kennst, und modelliere sie end‑to‑end: ein Chat‑Tool (OAuth), eine Google‑ähnliche Account‑Verbindung (OAuth mit Scopes) und ein Zahlungsanbieter (API‑Key plus Webhooks). Wenn dein Modell alle drei ohne Sonderfälle abbilden kann, skaliert es in der Regel auf 30.
Behandle das Verzeichnis wie ein Kontrollzentrum, nicht wie eine Marketing‑Seite. Jede Karte sollte schnell zeigen, wofür die Integration da ist, ob sie gerade funktioniert und welche einzelne nächste Aktion der Nutzer ausführen sollte. Wenn Nutzer erst klicken müssen, um zu erfahren „ist das verbunden?“, wirkt das Verzeichnis bei wachsender Zahl von Integrationen unzuverlässig.
Eine einfache Regel: Jede Integrationskarte sollte beantworten „was ist das“, „ist es gesund“ und „was nun“. Das heißt meist ein Name plus einzeiliger Zweck, ein Status mit einem Zeitpunkt (letzter Sync oder letzte Prüfung) und ein primärer Button, der sich je nach Zustand ändert. Alles Weitere gehört hinter „Manage“, damit das Scannen schnell bleibt.
Trenne, was du anbietest, von dem, was ein Workspace aktiviert hat, und von den vorhandenen Zugangsdaten. Verwende eine globale Integration (Katalogeintrag), eine Install (im Workspace aktiviert) und eine Connection (tatsächliches OAuth‑Konto, API‑Schlüssel oder Webhook). So vermeidest du das Durcheinander, bei dem „installiert“ und „verbunden“ vermischt werden.
Echte Teams brauchen oft mehr als ein externes Konto für denselben Anbieter. Marketing und Support können unterschiedliche Google‑Kalender verbinden oder ein Unternehmen mehrere Stripe‑Accounts haben. Modelliere mehrere Connections unter einer Install, damit das Verzeichnis sauber bleibt und Admins einzelne Accounts auf der Detailseite verwalten können.
Nutze eine kleine, pflegbare Menge an Labels: Not set up, In progress, Connected, Needs attention und Disabled. Leite diese Labels aus überprüfbaren Fakten ab — Token gültig, erforderliche Setup‑Schritte erledigt, letzter erfolgreicher Sync — statt sie direkt zu speichern. So verhinderst du veraltete Badges, die nach einer Behebung rot bleiben.
Mach den Setup‑Fortschritt zu einer kurzen Checkliste mit Pflicht‑ und optionalen Schritten. Speichere die Schrittdefinition pro Integration und die Schrittresultate pro Install, damit die UI z.B. „2 von 3 erforderlichen Schritten abgeschlossen“ anzeigen kann. Der nächste fehlende Pflichtschritt sollte immer sichtbar sein, ohne zu graben.
Beginne mit einer einfachen Rollenregel, die überall gilt, und füge nur bei sensiblen Integrationen zusätzliche Prüfungen hinzu. In vielen Produkten reichen Admin, Manager und Member: Admins dürfen alles, Manager können die meisten Integrationen einrichten, Members nutzen aktivierte Integrationen, dürfen Einstellungen aber nicht ändern. Für Zahlungen oder Lohnabrechnung füge eine einzelne „Billing/Payments admin“-Kennzeichnung hinzu, statt ein komplett neues Rollensystem zu erfinden.
Speichere nutzer‑sichtbare Konfiguration als normale Daten. Geheime Werte wie Refresh‑Tokens oder API‑Keys gehören in einen Secret‑Store oder verschlüsselte Felder mit strengen Zugriffskontrollen. Logge keine rohen Secrets, Autorisierungscodes oder Webhook‑Payloads; logge stattdessen Referenzen (connection_id) und sichere Metadaten (HTTP‑Status, Fehlercode).
Zeige eine Fehlermeldung, die erklärt, was passiert ist, was der Nutzer als nächstes tun soll und was dein System automatisch versucht. Wiederholungen sollten leise und nur für Probleme erfolgen, die der Nutzer nicht selbst beheben kann (z. B. Provider‑Ausfall). Bei abgelaufener Auth oder fehlenden Berechtigungen höre mit automatischen Versuchen auf und mache „Reconnect“ oder „Fix permissions“ zur primären Aktion.
Halte die Suche einfach: Anbietername zuerst, dann Kategorie. Biete Filter an, die Intent widerspiegeln, z. B. Connected, Needs attention, Not set up, damit Leute Probleme schnell finden. Wenn du Koder.ai verwendest, entwirf zuerst Katalogfelder, Statusregeln und Setup‑Schritte in Planning Mode, damit die generierte UI und das Backend beim Hinzufügen weiterer Integrationen konsistent bleiben.
