10 dec. 2025·8 min
Design av en integrationskatalog som skalar från 3 till 30 appar
Designa en integrationskatalog som skalar från 3 till 30 integrationer med enkel datamodell, tydliga statusar, behörigheter och UI för setup-progress.
Designa en integrationskatalog som skalar från 3 till 30 integrationer med enkel datamodell, tydliga statusar, behörigheter och UI för setup-progress.
Folk öppnar en integrationskatalog av en anledning: för att koppla verktyg och få dem att fungera utan att tänka på dem varje dag. Om skärmen får användare att gissa vad som är anslutet, vad som är trasigt eller vad de ska klicka på härnäst, sjunker förtroendet snabbt.
Med 3 integrationer kan ett enkelt rutnät med logotyper fungera. Med 30 faller det ihop: folk slutar skanna, supportärenden ökar och knappen “Connect” blir en fälla eftersom varje integration kan befinna sig i ett annat tillstånd.
Varje integrationskort (eller rad) bör svara på tre frågor vid en blick:
De flesta förvirringar kommer från kantfall som händer hela tiden i riktiga team. Någon kopplar Google med ett privat konto istället för företagskontot. En Stripe-token går ut och fakturering slutar synkroniseras. Ett Slack-workspace är anslutet, men den nödvändiga kanal-scopen gavs aldrig, så setup är “halvklart” även om UI ser okej ut.
En bra skärm gör de situationerna uppenbara. Istället för bara “Connected”, visa något som “Connected (behöver behörighet)” eller “Connected to: [email protected],” och lägg nästa steg direkt på kortet. Det håller folk ur gissningsläge och gör listan hanterbar när den växer.
Det enklaste sättet att skala en integrationskatalog är att separera:
Detta är läsbart vid 3 integrationer och fungerar fortfarande vid 30.
En Integration är katalogposten. Den är global och inte knuten till någon workspace.
En Install representerar att en workspace aktiverat den integrationen (t.ex.: “Slack är påslaget för Workspace A”).
En Connection representerar ett verkligt externt konto eller autentiseringsuppgift (t.ex.: “Slack workspace X via OAuth” eller “Stripe-konto Y via API-nyckel”). En Install kan ha många Connections.
En minimal uppsättning fält som brukar skala bra:
Spara användar-vänlig konfiguration (vald kanal, webhook-URL-namn, aktiverade events) på Install eller Connection som vanliga fält. Spara hemligheter (OAuth refresh tokens, API-nycklar, signing secrets) endast i en secrets store eller i ett krypterat fält med strikt åtkomstkontroll.
Lägg inte hemligheter, fulla auktoriseringskoder eller råa webhook-payloads i loggar. Om du måste logga något, logga referenser (connection_id) plus säker metadata (HTTP-status, felkod).
För att vara flexibel över OAuth, API-nycklar och webhooks, håll auth-specifika fält inne i Connection (token-metadata vs key-fingerprint vs webhook-verifieringsstatus). Håll UI-ytliga tillstånd (enabled och setup-progress) på Install.
Folk öppnar en integrationskatalog för att snabbt få svar på tre saker: fungerar det, hur långt är setup och vad ska jag göra härnäst. Om dina statusord är vaga ökar supportärenden och förtroendet minskar.
Börja med en liten uppsättning statusar som du kan hålla i åratal:
Föredra härledd status framför lagrad status. Lagrade etiketter glider isär: någon fixar ett fel men märket förblir rött. Härledd status beräknas från fakta du redan spårar, som om tokens är giltiga, om obligatoriska setupsteg är slutförda och om en admin pausat integrationen. Om du lagrar något, lagra de underliggande fakta (senaste lyckade sync, senaste felkod), inte den slutliga etiketten.
Setup-progress fungerar bäst som en kort checklista, med en tydlig uppdelning mellan obligatoriska och valfria steg. Modellera det som stegdefinitioner (statisk, per integration) plus stegresultat (per install).
Exempel: Slack kan kräva “Authorize workspace” och “Select channels”, med ett valfritt steg som “Enable message previews.” UI kan visa “2 av 3 obligatoriska steg klara” samtidigt som valfria objekt är synliga utan att blockera.
Flera connections under en integration kan göra katalogen rörig om du inte planerar för det. Håll ett kort per integration, visa antal connections och slå ihop status ärligt. Om någon connection är trasig, visa “Needs attention” med en hint som “1 av 4 workspaces behöver re-auth.” Översikten förblir ren men speglar verkligheten.
Integrationsbehörigheter blir röriga när allt behandlas som en enda switch. Det är tydligare att separera:
Börja med en lättviktig rollkontroll som gäller överallt. För många appar räcker tre roller: Admin, Manager och Member. Admins kan göra allt. Managers kan sätta upp de flesta integrationer för sitt team. Members kan använda redan aktiverade integrationer, men kan inte ändra inställningar.
Lägg sedan till per-integration-flaggar endast där det behövs. De flesta integrationer (kalender, chatt) kan följa standardrollregler. Känsliga (betalningar, lön, exports) bör kräva en extra kontroll som “Payments admin” eller “Billing manager.” Håll detta som en enkel boolean på install, inte ett helt nytt rollsystem.
En kartläggning som förblir läsbar:
Audit behöver inte vara tung, men den bör finnas. Spåra tillräckligt för att snabbt svara på support- och säkerhetsfrågor: vem anslöt, när credentials ändrades och vem som inaktiverade. En “Activity”-panel på detaljsidan med 5 till 20 senaste händelser är vanligtvis tillräckligt.
Exempel: Stripe kan visas för alla, men bara Admins (eller användare markerade “Billing manager”) kan ansluta det, rotera nycklar eller inaktivera utbetalningar. Slack kan låta Managers ansluta medan Members fortfarande kan ta emot Slack-notiser när det är aktivt.
Med 3 integrationer kan du visa allt. Med 30 måste katalogen snabbt svara på: “Vilka fungerar och vad ska jag göra härnäst?” Det renaste tillvägagångssättet är att separera skanning från handling.
Håll katalogvyn fokuserad på snabba beslut. Flytta tyngre kontroller till en detaljsida bakom en enkel “Manage”-knapp.
I listan visa bara det som stödjer nästa klick:
Kortets uppbyggnad spelar roll eftersom det bygger muskelminne. Primära åtgärden ska alltid betyda “nästa steg” baserat på tillstånd: Connect för nytt, Continue setup för partiellt, Reconnect när auth gått ut, och Manage när allt är friskt. Undvik två lika starka knappar på varje kort. Det gör sidan bullrig.
Exempel:
Tomma lägen bör guida utan att dumpa en manual på skärmen:
Detta håller sidan lugn vid 30 integrationer eftersom varje kort svarar: vad är det, fungerar det och vad gör jag nu?
Kataloglistan får folk till rätt integration. Detaljsidan är där de beslutar: sätta upp, fixa eller stänga av. Håll sidstrukturen konsekvent över alla integrationer, även när backend-arbetet skiljer sig.
Börja med en kompakt översikt: integrationsnamn, en enradig beskrivning och tydliga statusetiketter (Connected, Needs attention, Disabled). Lägg till en liten “Setup progress”-rad så användare vet om de är ett steg från klart eller fortfarande i början.
En enkel wizard fungerar bra: 3–6 steg, en skärm i taget, med “Back” alltid tillgängligt. Namnge steg i vardagligt språk (Connect account, Choose workspace, Pick data to sync, Confirm). Om ett steg har valfria val, markera dem som valfria istället för att gömma dem.
Om setup kan pausas, säg det tydligt: “Du kan fortsätta senare. Vi sparar dina val.” Det minskar rädslan att klicka bort.
Visa Connections som en liten tabell: kontonamn, ansluten av (användare), skapandedatum och senaste sync.
För “nästa sync”, undvik löften du inte kan hålla (exakta tider). Använd formuleringar du kan stå för, som “Next sync: scheduled soon” eller “Next sync: within the next hour,” baserat på vad ditt system faktiskt kan garantera.
Håll riskfyllda åtgärder borta från huvudvägen. Placera primära åtgärder högst upp (Continue setup, Reconnect). Placera Disable och Disconnect i en separat “Danger zone” längst ner med en kort förklaring av konsekvenser. Om du stöder roller, säg det i en mening (t.ex. “Endast admins kan disconnect”).
Lägg till en liten aktivitetslogg: senaste händelser (connected, token refreshed, sync failed), tidsstämplar och ett kort felmeddelande användare kan kopiera till ett supportärende.
Att lägga till en integration blir enklare om du behandlar det som en liten produkt. Den behöver en listing, ett sätt att ansluta, en plats att spara connection och tydliga utfall för framgång eller fel.
Lägg till integrationen i katalogen så att den syns i listan innan någon ansluter. Inkludera ett klart namn, kort beskrivning, ikon och en eller två kategorier (Messaging, Payments). Skriv upp vad setup kommer att kräva i enkla ord, som “Anslut ett konto” och “Välj workspace.” Här definierar du också vad integrationen senare kommer att behöva (OAuth-scopes, obligatoriska fält, stödda funktioner).
Välj den enklaste anslutningen som matchar leverantören:
När användaren slutfört flödet, skapa en Connection-post kopplad till deras workspace eller konto, inte bara användaren. Spara credentials säkert (kryptera i vila och undvik att visa hela secret igen). Spara det som behövs för support: leverantörens konto-ID, skapandetid, vem som anslöt och vilka behörigheter som gavs.
Kör ett enkelt test direkt (för Stripe: hämta kontouppgifter). Om det lyckas, visa Connected och markera progress som redo. Om det delvis lyckas (anslutet men saknar behörighet), markera Needs attention och peka på exakt åtgärd.
Visa ett tydligt meddelande, en rekommenderad åtgärd och en säker fallback. Exempel: “Vi kunde inte nå Stripe. Kontrollera API-nyckeln eller försök igen.” Håll katalogen användbar även när en integration är trasig.
Om du bygger på Koder.ai (koder.ai), kan du först skissa katalogen, setup-flödet och statusregler i Planning Mode, och sedan generera UI och backend från den planen.
Integrationer går sönder av tråkiga orsaker. Om din katalog inte kan förklara orsakerna tydligt, skyller användare på din app och support har inget att arbeta med.
Gruppera fel i kategorier som matchar verkliga åtgärder: inloggning utgånget, saknad behörighet, leverantörsavbrott eller rate limit. Behåll interna felkoder detaljerade, men visa användaren en kort etikett de förstår.
När något går sönder bör meddelandet svara tre saker: vad hände, vad användaren ska göra och vad systemet gör härnäst. Exempel: “Slack-anslutning utgånget. Återanslut för att fortsätta synkronisera. Vi försöker automatiskt igen när du återansluter.” Det är lugnare och mer åtgärdsbart än ett rått API-fel.
Autoretry bara när användaren inte kan fixa det själv. En enkel regeluppsättning räcker:
Statusar blir föråldrade om du inte uppdaterar dem. Lägg till ett lättvikts health-check-jobb som periodiskt bekräftar att tokens fortfarande fungerar, senaste sync kördes och att katalogens märke matchar verkligheten.
Behåll en liten händelseshistorik per install. Du behöver inte fulla loggar, bara tillräckligt med brödsmulor: tidsstämpel, händelse (“token refreshed”, “sync failed”), kort anledning och vem som utlöste det (användare eller system). Lägg till ett internt notes-fält så support kan dokumentera vad de ändrat och varför.
En katalog blir rörig snabbt när du passerar några få appar. Målet är enkelt: hjälp folk hitta det de behöver på sekunder, och hjälpa dem upptäcka problem utan att öppna varje kort.
Börja med grundläggande sök över integrationsnamn och kategori. De flesta användare skriver det de redan känner till (“Slack”, “Stripe”), så namnmatchning är viktigare än avancerad rankning. Kategorisök hjälper när de bara vet uppgiften (payments, messaging).
Filter bör spegla verklig avsikt. Dessa tre täcker oftast de flesta fall:
För att organisera listan, välj en primär gruppering och håll fast vid den. Kategorigruppering fungerar bra vid högre antal (CRM, Payments, Messaging). Popularitet kan också vara användbart, men bara om det speglar din användarbas, inte marknadsföring. Ett praktiskt standardval: visa mest använda först, och gruppera resten efter kategori.
Du behöver också en tydlig plan för “inte alla ska se allt.” Om en integration ligger bakom en feature-flagga eller plan-nivå, göm den för de flesta användare eller visa den inaktiverad med en kort orsak som “Business plan.” Undvik att visa en sida full av nedtonade kort. Det får skärmen att kännas trasig.
Håll prestandan snabb genom att behandla lista och detalj som separata laddningar. Paginera eller virtualisera listan så att du inte renderar 30 tunga kort samtidigt, och lazy-loada detaljer först när en användare öppnar en integration. Katalogen kan visa sammanfattande fält (Slack: Connected, Google: Needs attention, Stripe: Not set up) medan detaljsidan hämtar full connection-historik.
Föreställ dig en team-workspace-app som heter Pinework. Den har två roller: Admin och Member. Admins kan ansluta verktyg och ändra inställningar. Members kan använda anslutna verktyg men inte lägga till eller ta bort dem.
I Pineworks integrationskatalog visar varje kort en tydlig etikett (Connected, Needs setup, Error), en kort “vad det gör”-rad och setup-progress som “2 av 3 steg.” Folk kan se vad som fungerar och vad som väntar utan att klicka runt.
Slack används för notiser. En Admin öppnar Slack och ser: Status: Connected, Setup: “3 av 3 steg.” Members ser Slack också, men huvudåtgärden är inaktiverad och visar “Be en admin att hantera.” Om Slack kopplas bort kan Members fortfarande se vad som bröts, men inte reconnect-kontrollerna.
Google används för kalendrar. Pinework stödjer två avdelningar, så den tillåter flera connections. Google-kortet visar: Status: Connected (2 konton). Under det listas “Marketing Calendar” och “Support Calendar.” Setup kan fortfarande vara klar, och detaljsidan visar två separata connections så en Admin kan återkalla bara ett.
Stripe används för fakturering. Ett vanligt partiellt setup är: kontot är anslutet, men webhooks är inte färdiga. Kortet visar: Status: Needs setup, Progress: “2 av 3 steg,” med en varning som “Payments kanske inte synkar.” Detaljvyn visar det återstående steget tydligt:
Det undviker det smärtsamma “det ser anslutet ut men ingenting funkar”-läget.
En integrationskatalog brukar brytas när en app växer från några integrationer till dussintals. Problemen är sällan “stora tekniska” – det är små fel i märkning och modellering som förvirrar folk varje dag.
Ett vanligt problem är att blanda ihop “installed” och “connected.” Installed betyder oftast “tillgänglig i din workspace.” Connected betyder att verkliga credentials finns och data kan flöda. När de blandas ihop klickar användare på en integration som ser redo ut och möts av en återvändsgränd.
Ett annat misstag är att uppfinna för många status-stater. Team börjar med en enkel badge och lägger sedan till kantfall: pending, verifying, partial, paused, degraded, blocked, expiring och fler. Med tiden drar de här etiketterna ifrån verkligheten eftersom ingen håller dem konsekventa. Håll en liten uppsättning knuten till kontroller du faktiskt kan köra.
Dolda behörigheter ställer också till problem. Någon ansluter ett konto och upptäcker senare att integrationen hade större åtkomst än väntat. Gör scope uppenbart innan sista “Connect”-steget och visa det igen på detaljsidan så admins kan granska.
Många appar behöver flera connections: två Slack-workspaces, flera Stripe-konton eller ett delat Google-konto plus personliga konton. Om du hårdkodar “en integration = en connection” kommer du få fula nödlösningar senare.
Planera för:
Håll kataloglistan lätt. När du stoppar in loggar, fältmappningar och långa beskrivningar i översikten, blir skanning långsammare. Använd listan för namn, kort syfte och setup-progress. Lägg historik och avancerade inställningar på detaljsidan.
En skalbar integrationskatalog handlar om en enkel modell och ett ärligt UI. Om användare kan svara tre frågor snabbt känns systemet förutsägbart: vad är anslutet, vad är trasigt och vad gör jag härnäst?
Checklista innan lansering:
Nästa steg: välj tre integrationer du redan kan väl och modellera dem från början till slut: ett chattverktyg (OAuth), en Google-liknande kontoanslutning (OAuth med scopes) och ett betalningsverktyg (API-nyckel plus webhooks). Om din modell kan uttrycka alla tre utan specialfall, skalar den oftast till 30.
Behandla den som en kontrollpanel, inte en marknadssida. Varje kort ska snabbt visa vad integrationen gör, om den fungerar nu och den enda nästa åtgärden användaren bör ta. Om användare måste klicka bara för att ta reda på “är detta anslutet?”, kommer katalogen att kännas opålitlig när den växer.
En enkel regel är: ett integrationskort ska svara på “vad är det”, “är det friskt” och “vad nu”. Det betyder oftast ett namn plus en kort ändamålsrad, en status med en nylig tidsstämpel (senaste sync eller kontroll) och en primär knapp som byter beroende på tillstånd. Lägg allt annat bakom “Manage” så att översikten förblir snabb att skanna.
Separera vad du erbjuder från vad en workspace aktiverat och vilka uppgifter som faktiskt finns. Använd en global Integration (katalogpost), en Install (aktiverat i en workspace) och en Connection (verkligt OAuth-konto, API-nyckel eller webhook). Det förhindrar förvirring där “installed” och “connected” blandas ihop och användare inte kan avgöra vad som är verkligt.
För riktiga team behövs ofta mer än ett externt konto för samma leverantör. Marketing och Support kan till exempel ansluta olika Google-kalendrar, eller ett företag kan ha flera Stripe-konton. Att modellera flera Connections under en Install håller katalogen ren samtidigt som administratörer kan hantera konton individuellt på detaljsidan.
Använd en liten uppsättning etiketter du kan hålla konsekvent, t.ex. Not set up, In progress, Connected, Needs attention och Disabled. Härled sedan dessa etiketter från fakta du kan kontrollera, som token giltighet, obligatoriska setup-steg slutförda och senaste lyckade sync. Det undviker att märken blir föråldrade och fortfarande röda efter att problemet är åtgärdat.
Gör setup-progress till en kort checklista med obligatoriska steg och valfria steg som inte blockerar färdigställandet. Spara stegdefinitionerna per integration och stegresultaten per install, så UI kan visa något i stil med “2 av 3 obligatoriska steg slutförda.” Användaren ska alltid se nästa sak som saknas utan att behöva gräva.
Börja med en enkel rollregel som gäller överallt, och lägg bara till extra kontroller för känsliga integrationer. För många produkter räcker det med att Admins kan konfigurera, Managers kan konfigurera de flesta verktyg, och Members kan använda aktiverade verktyg men inte ansluta eller ändra inställningar. För betalningar eller lön, lägg till en enda flagga som “billing/payments admin” i stället för att uppfinna en helt ny rollstruktur.
Spara synlig konfiguration som vanliga fält, men lagra hemligheter som refresh tokens och API-nycklar i en hemlighetshanterare eller krypterade fält med strikt åtkomstkontroll. Logga aldrig råa hemligheter, fulla auktoriseringskoder eller webhook-payloads. Logga istället referenser (connection_id) och säker metadata (HTTP-status, felkod). Det minskar risk och underlättar efterlevnad och support.
Visa ett felmeddelande som förklarar vad som hände, vad användaren bör göra och vad systemet kommer försöka göra automatiskt. Återförsök ska vara tysta och begränsade till saker användaren inte kan åtgärda, t.ex. tillfälliga leverantörsavbrott eller rate limits. För utgången auth eller saknade behörigheter, stoppa återförsök och gör “Reconnect” eller “Fix permissions” till primär åtgärd.
Håll sökningen enkel: prioritera leverantörens namn först, sedan kategori. Lägg till filter som speglar avsikt, t.ex. Connected, Needs attention och Not set up, så folk snabbt kan hitta problem. Om du bygger i Koder.ai, utforma katalogfält, statusregler och setup-steg i Planning Mode först så att den genererade UI:n och backend förblir konsekvent när du lägger till fler integrationer.