Ontwerp een integrations-directory die schaalbaar is van 3 naar 30 integraties met een eenvoudig datamodel, duidelijke statussen, permissies en een setup-voortgangs-UI.
Mensen openen een integraties-directory om één reden: tools te koppelen en ze te laten werken zonder er elke dag over na te denken. Als het scherm gebruikers laat raden wat verbonden is, wat kapot is of wat ze vervolgens moeten klikken, daalt het vertrouwen snel.
Bij 3 integraties werkt een eenvoudige rasterweergave met logo's vaak nog. Bij 30 valt dat uit elkaar: mensen stoppen met scannen, supporttickets nemen toe en de "Connect"-knop wordt een val omdat elke integratie in een andere status kan verkeren.
Elk integratiekaartje (of rij) moet in één oogopslag drie vragen beantwoorden:
De meeste verwarring komt van randgevallen die constant bij echte teams voorkomen. Iemand verbindt Google met een persoonlijk account in plaats van het bedrijfsaccount. Een Stripe-token verloopt en facturering stopt met synchroniseren. Een Slack-workspace is verbonden, maar de vereiste channel-scope is nooit gegeven, dus de setup is “half klaar” hoewel de UI er prima uitziet.
Een goed scherm maakt die situaties duidelijk. In plaats van alleen “Connected” laat je iets zien als “Connected (has permissie nodig)” of “Connected to: [email protected]” en zet je de volgende stap direct op het kaartje. Dat voorkomt giswerk en houdt de lijst beheersbaar naarmate hij groeit.
De eenvoudigste manier om een integrations-directory schaalbaar te maken, is scheiden:
Dit blijft leesbaar bij 3 integraties en werkt nog steeds bij 30.
Een Integratie is het catalogus-item. Het is globaal en niet gebonden aan een werkruimte.
Een Installatie vertegenwoordigt dat een werkruimte die Integratie heeft ingeschakeld (bijv.: “Slack is ingeschakeld voor Werkruimte A”).
Een Connectie vertegenwoordigt een echt extern account of credential (bijv.: “Slack workspace X via OAuth” of “Stripe account Y via API key”). Eén Installatie kan meerdere Connecties hebben.
Een minimale set velden die goed schaalt:
slack), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (korte tekst), created_atMarketing Slack), connection_status (ok/expired/error), external_account_id (indien bekend), scopes/permissions_granted, last_success_at, created_atSla zichtbare configuratie op (gekozen kanaal, webhook-URL bijnaam, ingeschakelde events) op de Installatie of Connectie als gewone data. Sla geheimen (OAuth refresh tokens, API-keys, signing secrets) alleen op in een secrets store of een versleuteld veld met strikte toegangscontrole.
Zet geen geheimen, volledige autorisatiecodes of ruwe webhook-payloads in logs. Als je iets moet loggen, log referenties (connection_id) plus veilige metadata (HTTP-status, foutcode).
Om flexibel te blijven tussen OAuth, API-keys en webhooks, houd auth-specifieke velden binnen Connectie (tokenmetagegevens versus key-fingerprint versus webhook verificatiestatus). Houd UI-gezinde status (enabled en setup-voortgang) op de Installatie.
Mensen openen een integrations-directory om drie dingen snel te weten: werkt het, hoever is de setup en wat moet ik nu doen. Als je statuswoorden vaag zijn, neemt support toe en daalt het vertrouwen.
Begin met een kleine set statussen die je jarenlang kunt aanhouden:
Geef de voorkeur aan afgeleide status boven opgeslagen labels. Opgeslagen labels lopen uit de pas: iemand lost een fout op, maar het label blijft rood. Afgeleide status wordt berekend uit feiten die je al bijhoudt, zoals of tokens geldig zijn, of verplichte setup-stappen zijn voltooid en of een admin de integratie heeft gepauzeerd. Als je iets opslaat, bewaar dan de onderliggende feiten (laatste succesvolle sync, laatste foutcode), niet het eindlabel.
Setup-voortgang werkt het beste als een korte checklist, met een duidelijke scheiding tussen verplicht en optioneel. Modelleer het als stapdefinities (statisch, per integratie) plus stapresultaten (per install).
Voorbeeld: Slack kan vereisen “Autorisatie workspace” en “Selecteer kanalen”, met een optionele stap zoals “Enable message previews.” De UI kan “2 van 3 verplichte stappen voltooid” tonen en tegelijk optionele items zichtbaar maar niet blokkerend houden.
Meerdere connecties onder één integratie kunnen een directory rommelig maken als je er niet op voorbereidt. Houd één kaart per integratie, toon het aantal connecties en vat de status eerlijk samen. Als een van de connecties kapot is, toon “Needs attention” met een hint zoals “1 van 4 workspaces moet opnieuw worden geauthenticeerd.” Het overzicht blijft schoon, maar weerspiegelt de werkelijkheid.
Integratiepermissies worden rommelig wanneer alles als één schakel wordt behandeld. Het is duidelijker om te scheiden:
Begin met een lichtgewicht rolcontrole die overal geldt. Voor veel apps volstaan drie rollen: Admin, Manager en Member. Admins kunnen alles. Managers kunnen de meeste integraties voor hun team instellen. Members kunnen ingeschakelde integraties gebruiken, maar geen instellingen wijzigen.
Voeg daarna per-integratie permissievlaggen alleen waar dat nodig is. De meeste integraties (agenda, chat) kunnen de standaard rolregels volgen. Gevoelige integraties (betalingen, loonstrook, exports) zouden een extra check moeten vereisen zoals “Payments admin” of “Billing manager.” Houd dit als een eenvoudige boolean op de install, niet als een nieuw rollenstelsel.
Een leesbare mapping:
Audit hoeft niet zwaar te zijn, maar moet bestaan. Volg genoeg om support- en beveiligingsvragen snel te beantwoorden: wie het verbonden heeft, wanneer credentials veranderden en wie het heeft uitgeschakeld. Een “Activity”-paneel op de detailpagina met 5 tot 20 recente events is meestal voldoende.
Voorbeeld: Stripe kan zichtbaar zijn voor iedereen, maar alleen Admins (of gebruikers met de vlag “Billing manager”) mogen het verbinden, keys roteren of uitbetalingen uitschakelen. Slack kan Managers toestaan te verbinden, terwijl Members nog steeds Slack-notificaties ontvangen zodra het is ingeschakeld.
Bij 3 integraties kun je alles tonen. Bij 30 moet de directory één vraag snel beantwoorden: “Welke werken en wat moet ik hierna doen?” De schoonste aanpak is scannen scheiden van doen.
Houd de directoryweergave gericht op snelle beslissingen. Schuif zwaardere controls naar een detailpagina achter één “Manage”-knop.
In de lijst toon je alleen wat de volgende klik ondersteunt:
De anatomie van het kaartje is belangrijk omdat het muscle memory bouwt. De primaire actie moet altijd “de volgende stap” betekenen op basis van de staat: Connect voor nieuw, Continue setup voor gedeeltelijk, Reconnect bij verlopen auth, en Manage wanneer alles gezond is. Vermijd twee even luide knoppen op elk kaartje — dat maakt de pagina rommelig.
Voorbeeld:
Leegtoestanden moeten leiden zonder een handleiding te dumpen:
Dat houdt de pagina rustig bij 30 integraties omdat elk kaartje antwoordt: wat is het, is het oké, en wat doe ik nu?
De directorylijst brengt mensen naar de juiste integratie. De detailpagina is waar ze beslissen: instellen, repareren of uitzetten. Houd de paginastructuur consistent over elke integratie, ook als de backend anders werkt.
Begin met een compact overzicht: integratienaam, één-regelige omschrijving en duidelijke statuslabels (Connected, Needs attention, Disabled). Voeg een kleine “Setup voortgang”-regel toe zodat gebruikers weten of ze nog één stap moeten doen of net begonnen zijn.
Een eenvoudige wizard werkt goed: 3 tot 6 stappen, één scherm per keer, met altijd een “Back”-knop. Benoem stappen in gewone taal (Account verbinden, Werkruimte kiezen, Gegevens kiezen om te synchroniseren, Bevestigen). Als een stap optionele keuzes heeft, label ze dan als optioneel in plaats van ze te verbergen.
Als setup gepauzeerd kan worden, zeg dat dan duidelijk: “Je kunt later verder gaan. We bewaren je keuzes.” Dat vermindert de angst om weg te klikken.
Toon Connecties als een kleine tabel: accountnaam, verbonden door (gebruiker), aanmaakdatum en laatste sync.
Voor “volgende sync”, vermijd beloftes die je niet kunt waarmaken (zoals exacte tijden). Gebruik formuleringen die je kunt garanderen, zoals “Next sync: gepland binnenkort” of “Next sync: binnen het uur”, gebaseerd op wat je systeem echt kan leveren.
Houd risicovolle acties weg uit het hoofdpad. Zet primaire acties bovenaan (Continue setup, Reconnect). Plaats Disable en Disconnect in een aparte “Danger zone” sectie onderaan met een korte uitleg van de impact. Als je rollen ondersteunt, vermeld dat in één zin (bijv. “Alleen admins kunnen disconnecten”).
Voeg een klein activiteitenlog toe: recente events (connected, token refreshed, sync failed), timestamps en een korte foutmelding die gebruikers kunnen kopiëren naar een supportticket.
Een integratie toevoegen is eenvoudiger als je het als een klein product behandelt. Het heeft een listing nodig, een manier om te verbinden, een plaats om de connectie op te slaan en duidelijke uitkomsten voor succes of falen.
Voeg de integratie toe aan je catalogus zodat deze in de directory verschijnt voordat iemand hem verbindt. Voeg een duidelijke naam, korte beschrijving, icoon en één of twee categorieën toe (Messaging, Payments). Schrijf setup-verwachtingen in eenvoudige woorden, zoals “Verbind een account” en “Kies een werkruimte.” Dit is ook waar je definieert wat de integratie later nodig zal hebben (OAuth-scopes, vereiste velden, ondersteunde features).
Kies de eenvoudigste connectiemethode die bij de provider past:
Wanneer de gebruiker de flow voltooit, maak dan een Connectie-record gekoppeld aan hun werkruimte of account, niet alleen aan de gebruiker. Bewaar credentials veilig (versleutel in rust en vermijd het opnieuw tonen van het volledige geheim). Sla basisgegevens op die je voor support nodig hebt: provider account ID, aanmaaktijd, wie het verbonden heeft en welke permissies werden gegeven.
Voer direct een eenvoudige test uit (voor Stripe: haal accountdetails op). Als het slaagt, toon Connected en markeer de voortgang als gereed. Als het gedeeltelijk slaagt (verbonden maar permissie ontbreekt), markeer als Needs attention en wijs naar de exacte fix.
Toon één duidelijke boodschap, één aanbevolen actie en een veilige fallback. Bijvoorbeeld: “We konden Stripe niet bereiken. Controleer de API-key of probeer opnieuw.” Houd de directory bruikbaar, zelfs als één integratie kapot is.
Als je op Koder.ai (koder.ai) bouwt, kun je eerst de catalogus, setup-flow en statusregels in Planning Mode opstellen en daarna de UI en backend genereren vanuit dat plan.
Integraties falen om alledaagse redenen. Als je directory die redenen niet duidelijk kan uitleggen, geven gebruikers je app de schuld en heeft support niets om mee te werken.
Groepeer falen in buckets die overeenkomen met echte oplossingen: login verlopen, ontbrekende permissie, provider outage of rate limit. Houd interne foutcodes gedetailleerd, maar toon gebruikers een korte, begrijpelijke label.
Wanneer iets faalt, moet het bericht drie dingen beantwoorden: wat is er gebeurd, wat moet de gebruiker doen en wat doet jouw systeem daarna. Voorbeeld: “Slack-verbinding is verlopen. Verbind opnieuw om door te gaan. We proberen automatisch opnieuw zodra je opnieuw verbindt.” Dat is rustiger en actiegerichter dan een ruwe API-fout.
Auto-retry alleen wanneer de gebruiker het niet zelf kan oplossen. Een eenvoudige regelset is genoeg:
Statussen worden verouderd tenzij je ze ververst. Voeg een lichte health-check job toe die periodiek controleert of tokens nog werken, of de laatste sync heeft gedraaid en of het directory-badge overeenkomt met de realiteit.
Bewaar een kleine eventgeschiedenis per install. Je hebt geen volledige logs nodig, alleen voldoende breadcrumbs: timestamp, event ("token refreshed", "sync failed"), korte reden en wie het triggerde (gebruiker of systeem). Voeg een intern-only notitieveld toe zodat support kan vastleggen wat ze veranderden en waarom.
Een directory wordt snel rommelig zodra je voorbij een handvol apps gaat. Het doel is simpel: help mensen vinden wat ze nodig hebben in seconden en laat ze problemen zien zonder elk kaartje te openen.
Begin met basiszoekfunctie over integratienaam en categorie. De meeste gebruikers typen wat ze al kennen ("Slack", "Stripe"), dus naamsmatching is belangrijker dan slimme ranking. Categorie-zoeken helpen als ze alleen de taak kennen (payments, messaging).
Filters moeten echte intenties weerspiegelen. Deze drie dekken meestal de meeste scenario's:
Voor het organiseren van de lijst kies je één primaire groepering en houd je je eraan. Categorie-groepering werkt goed bij grotere aantallen (CRM, Payments, Messaging). Populariteit kan nuttig zijn, maar alleen als het jouw gebruikersbasis weerspiegelt, niet marketing. Een praktisch standaard: toon eerst meest gebruikt, groepeer de rest op categorie.
Je hebt ook een plan nodig voor “niet iedereen zou alles moeten zien.” Als een integratie achter een feature-flag of abonnementstier zit, verberg het dan voor de meeste gebruikers of toon het uitgeschakeld met een korte reden zoals “Business plan.” Vermijd een pagina vol grijze kaartjes — dat geeft een kapotte indruk.
Houd performance vloeiend door lijst en details als aparte loads te behandelen. Pagineer of virtualiseer de lijst zodat je niet 30 zware kaartjes tegelijk rendert, en laad details alleen als een gebruiker een integratie opent. De directory kan samenvattende velden tonen (Slack: Connected, Google: Needs attention, Stripe: Not set up) terwijl de detailpagina de volledige connection-geschiedenis ophaalt.
Stel je een teamworkspace-app voor genaamd Pinework. Hij heeft twee rollen: Admin en Member. Admins kunnen tools verbinden en instellingen wijzigen. Members kunnen verbonden tools gebruiken maar niet toevoegen of verwijderen.
In Pinework's integrations-directory toont elk kaartje een duidelijk label (Connected, Needs setup, Error), een korte “wat doet het”-regel en voortgang zoals “2 van 3 stappen.” Mensen zien wat werkt en wat wacht zonder rond te klikken.
Slack wordt gebruikt voor notificaties. Een Admin opent Slack en ziet: Status: Connected, Setup: “3 van 3 stappen.” Members zien Slack ook, maar de hoofdfunctie is uitgeschakeld en toont “Vraag een Admin om te beheren.” Als Slack loskoppelt, kunnen Members nog steeds zien wat er kapot is, maar niet de reconnect-controls gebruiken.
Google wordt gebruikt voor agenda's. Pinework ondersteunt twee afdelingen, dus het staat meerdere connecties toe. De Google-kaart toont: Status: Connected (2 accounts). Daaronder staat kort “Marketing Calendar” en “Support Calendar.” De setup kan compleet zijn, en de detailpagina toont twee afzonderlijke connecties zodat een Admin er één kan intrekken.
Stripe wordt gebruikt voor facturatie. Een veelvoorkomende gedeeltelijke setup is: het account is verbonden, maar webhooks zijn nog niet afgerond. Het kaartje toont: Status: Needs setup, Voortgang: “2 van 3 stappen,” met een waarschuwing als “Betalingen synchroniseren mogelijk niet.” De detailweergave maakt de resterende stap duidelijk:
Zo voorkom je de pijnlijke situatie “het lijkt verbonden maar niets werkt”.
Een integrations-directory loopt meestal vast wanneer een app groeit van een paar integraties naar tientallen. De problemen zijn zelden groot technisch werk; het zijn kleine labeling- en modelleerfouten die mensen dagelijks verwarren.
Een veelvoorkomend probleem is het door elkaar halen van “installed” versus “connected.” Installed betekent meestal “beschikbaar in je werkruimte.” Connected betekent dat er echte credentials bestaan en data kan stromen. Als die twee vervloeien, klikken gebruikers op een integratie die er klaar uitziet en stuiten op een doodlopende weg.
Nog een fout is te veel statusstaten bedenken. Teams beginnen met een simpel badge, voegen dan randgevallen toe: pending, verifying, partial, paused, degraded, blocked, expiring, enz. Na verloop van tijd lopen die labels uit de pas omdat niemand ze consistent houdt. Houd een kleine set aan die gebaseerd is op checks die je daadwerkelijk kunt uitvoeren: Not connected, Connected, Needs attention.
Verborgen permissies veroorzaken ook problemen. Iemand verbindt een account en ontdekt later dat de integratie bredere toegang had dan verwacht. Maak de scope duidelijk voor de laatste “Connect”-stap en toon het opnieuw op de detailpagina zodat admins het kunnen auditen.
Veel apps hebben meerdere connecties nodig: twee Slack-workspaces, meerdere Stripe-accounts, of een gedeeld Google-account plus persoonlijke accounts. Als je hardcode “één integratie = één connectie”, krijg je later lelijke workarounds.
Plan voor:
Houd de lijstweergave licht. Als je hem volstouwt met logs, veldmappings en lange omschrijvingen, vertraagt scannen. Gebruik de lijst voor naam, korte doelomschrijving en setup-voortgang. Zet geschiedenis en geavanceerde instellingen op de detailpagina.
Een schaalbare integrations-directory komt neer op een simpel model en een eerlijke UI. Als gebruikers drie vragen snel kunnen beantwoorden, voelt het systeem voorspelbaar: wat is verbonden, wat is kapot en wat moet ik nu doen?
Checklist voordat je live gaat:
Als vervolgstap kies je drie integraties die je goed kent en modelleer je ze end-to-end: een chattool (OAuth), een Google-achtige accountverbinding (OAuth met scopes) en een betalingsprovider (API-key plus webhooks). Als je model alledrie zonder speciale gevallen kan beschrijven, schaalt het doorgaans naar 30.
Behandel het als een bedieningspaneel, niet als een marketingpagina. Elk kaartje moet snel tonen waar de integratie voor is, of hij op dit moment werkt, en welke ene vervolgstap de gebruiker moet nemen. Als gebruikers moeten klikken alleen om te ontdekken of iets verbonden is, voelt de directory onbetrouwbaar zodra hij groter wordt.
Een eenvoudige regel: een integratiekaart moet beantwoorden “wat is het”, “is het gezond” en “wat nu”. Dat betekent meestal een naam plus één-regelige omschrijving, een status met een recente timestamp (laatste sync of check), en één primaire knop die verandert op basis van de staat. Houd alles anders achter “Manage” zodat scannen snel blijft.
Scheid wat je aanbiedt van wat een werkruimte heeft ingeschakeld en welke credentials bestaan. Gebruik een globale Integratie (catalogusitem), een Installatie (ingeschakeld in een werkruimte) en een Connection (echt OAuth-account, API-key of webhook). Dit voorkomt de verwarring waarin “geïnstalleerd” en “verbonden” door elkaar worden gebruikt en gebruikers niet kunnen zien wat echt is.
Realistische teams hebben vaak meer dan één extern account van dezelfde provider. Marketing en Support kunnen verschillende Google-calendars koppelen, of een organisatie kan meerdere Stripe-accounts hebben. Meerdere Connections onder één Install houden de directory schoon en maken het mogelijk voor admins om afzonderlijke accounts op de detailpagina te beheren.
Gebruik een kleine set labels die je consistent kunt houden, bijvoorbeeld Not set up, In progress, Connected, Needs attention en Disabled. Leid die labels af van feiten die je kunt controleren, zoals token-validiteit, voltooide setup-stappen en de laatste succesvolle sync. Zo voorkom je verouderde badges die rood blijven nadat het probleem is opgelost.
Maak setup-voortgang een korte checklist met verplichte en optionele stappen. Bewaar stapdefinities per integratie en stapresultaten per install, zodat de UI iets kan tonen als “2 van 3 verplichte stappen voltooid”. De gebruiker moet altijd de volgende ontbrekende verplichte stap direct kunnen zien.
Begin met eenvoudige rolregels die overal gelden en voeg extra controles alleen toe voor gevoelige integraties. Voor veel producten volstaan Admins om te configureren, Managers om de meeste tools te instellen en Members om ingeschakelde tools te gebruiken zonder instellingen te wijzigen. Voor betalingen of loonadministratie voeg je één extra vlag toe (bijv. “billing/payments admin”) in plaats van een compleet nieuw rollenstelsel.
Sla zichtbare configuratie op als gewone data, maar bewaar geheimen zoals refresh tokens en API-keys in een secrets store of versleutelde velden met strikte toegangscontrole. Log nooit onversleutelde geheimen, autorisatiecodes of ruwe webhook-payloads; log veilige metadata en referenties zoals een connection-id. Dat vermindert risico en maakt compliance en support eenvoudiger.
Toon een foutmelding die uitlegt wat er is gebeurd, wat de gebruiker moet doen en wat jouw systeem automatisch zal proberen. Retries moeten stil en beperkt zijn voor zaken die de gebruiker niet kan repareren, zoals tijdelijke outages of rate limits. Bij verlopen auth of ontbrekende permissies stop je met retries en maak je “Reconnect” of “Fix permissions” de primaire actie.
Houd zoeken simpel en gericht op hoe mensen denken: providernaam eerst, dan categorie. Voeg filters toe die overeenkomen met intentie, zoals Connected, Needs attention en Not set up, zodat mensen snel problemen vinden. Als je in Koder.ai bouwt, stel dan eerst catalogusvelden, statusregels en setup-stappen in Planning Mode op zodat de gegenereerde UI en backend consistent blijven terwijl je meer integraties toevoegt.