Concevez un répertoire d'intégrations qui passe de 3 à 30 intégrations avec un modèle de données simple, des statuts clairs, des permissions et une UI de progression de configuration.
Les gens ouvrent un répertoire d'intégrations pour une raison : connecter des outils et les garder fonctionnels sans y penser au quotidien. Si l'écran oblige les utilisateurs à deviner ce qui est connecté, ce qui est cassé ou quoi cliquer ensuite, la confiance chute vite.
Avec 3 intégrations, une grille simple de logos peut suffire. Avec 30, ça s'effondre : les gens arrêtent de parcourir, les tickets support augmentent, et le bouton « Connect » devient un piège parce que chaque intégration peut être dans un état différent.
Chaque carte (ou ligne) d'intégration doit répondre à trois questions en un coup d'œil :
La plupart des confusions viennent des cas limites qui arrivent constamment dans les équipes réelles. Quelqu'un connecte Google avec un compte personnel au lieu du compte entreprise. Un token Stripe expire et la facturation ne se synchronise plus. Un workspace Slack est connecté, mais le scope de canal requis n'a jamais été accordé, donc la configuration est « à moitié faite » même si l'UI semble correcte.
Un bon écran rend ces situations évidentes. Au lieu de juste « Connected », affichez par exemple « Connected (needs permission) » ou « Connected to: [email protected] », et proposez l'étape suivante directement sur la carte. Cela évite les supputations et garde la liste lisible à mesure qu'elle grandit.
La façon la plus simple de faire évoluer un répertoire d'intégrations est de séparer :
Cela reste lisible à 3 intégrations et fonctionne encore à 30.
Une Intégration est l'entrée du catalogue. Elle est globale, non liée à un workspace.
Une Installation (Install) représente un workspace qui active cette Intégration (par exemple : « Slack est activé pour Workspace A »).
Une Connection représente un vrai compte externe ou identifiant (par exemple : « workspace Slack X via OAuth » ou « compte Stripe Y via API key »). Une Install peut avoir plusieurs Connections.
Un ensemble minimal de champs qui tient bien :
Stockez la configuration visible par l'utilisateur (canal sélectionné, surnom d'URL de webhook, événements activés) sur l'Install ou la Connection en tant que données normales. Stockez les secrets (tokens de refresh OAuth, clés API, secrets de signature) seulement dans un coffre de secrets ou un champ chiffré avec des contrôles d'accès stricts.
Ne mettez pas de secrets, de codes d'autorisation complets ou de payloads bruts de webhook dans les logs. Si vous devez logger quelque chose, loggez des références (connection_id) et des métadonnées sûres (statut HTTP, code d'erreur).
Pour rester flexible face à OAuth, API keys et webhooks, conservez les champs spécifiques à l'auth dans Connection (métadonnées du token vs empreinte de clé vs statut de vérification du webhook). Gardez l'état visible par l'UI (activé et progression de configuration) sur Install.
Les gens ouvrent un répertoire d'intégrations pour répondre rapidement à trois choses : est‑ce que ça marche, à quel point la configuration est avancée, et que dois‑je faire ensuite. Si vos mots‑clé de statut sont vagues, les tickets support augmentent et la confiance diminue.
Commencez avec un petit ensemble de statuts que vous pouvez garder des années :
Privilégiez un statut dérivé plutôt qu'un statut stocké. Les labels stockés dérivent : quelqu'un corrige une erreur, mais le badge reste rouge. Le statut dérivé se calcule à partir de faits que vous suivez déjà, comme la validité des tokens, la complétion des étapes requises et si un admin a mis l'intégration en pause. Si vous stockez quelque chose, stockez les faits sous‑jacents (dernier sync réussi, dernier code d'erreur), pas le libellé final.
La progression se modélise mieux comme une courte checklist, avec une séparation claire entre requis et optionnel. Modélisez-la comme des définitions d'étapes (statiques, par intégration) plus des résultats d'étapes (par install).
Exemple : Slack peut exiger « Autoriser le workspace » et « Sélectionner les canaux », avec une étape optionnelle comme « Activer les aperçus de messages ». L'UI peut afficher « 2 des 3 étapes requises complétées » tout en gardant visibles les éléments optionnels sans bloquer.
Plusieurs connections sous une même intégration peuvent transformer un répertoire en bazar si vous n'anticipiez pas. Gardez une carte par intégration, affichez le nombre de connections et faites remonter le statut honnêtement. Si une connection est cassée, affichez « Needs attention » avec un indice comme « 1 des 4 workspaces nécessite une ré‑auth ». L'ensemble reste propre mais fidèle à la réalité.
Les permissions d'intégrations deviennent compliquées quand tout est traité comme un seul interrupteur. Il est plus clair de séparer :
Commencez par un contrôle de rôles léger qui s'applique partout. Pour beaucoup d'apps, trois rôles suffisent : Admin, Manager et Member. Les Admins peuvent tout faire. Les Managers peuvent configurer la plupart des intégrations pour leur équipe. Les Members peuvent utiliser les intégrations déjà activées, mais ne peuvent pas en modifier les réglages.
Ajoutez ensuite des flags de permission par intégration seulement quand c'est nécessaire. La plupart des intégrations (calendrier, chat) peuvent suivre les règles par défaut de rôles. Les intégrations sensibles (paiements, paies, exports) devraient nécessiter une vérification supplémentaire comme « Payments admin » ou « Billing manager ». Gardez cela comme un simple booléen sur l'install, pas un tout nouveau système de rôles.
Une cartographie lisible :
L'audit n'a pas besoin d'être lourd, mais il doit exister. Suivez assez pour répondre aux questions support et sécurité rapidement : qui a connecté, quand les identifiants ont changé, et qui a désactivé. Un panneau « Activity » sur la page de détail avec 5 à 20 événements récents suffit souvent.
Exemple : Stripe peut être visible par tous, mais seuls les Admins (ou les utilisateurs marqués « Billing manager ») peuvent le connecter, faire pivoter les clés ou désactiver les payouts. Slack peut permettre aux Managers de connecter, tandis que les Members reçoivent quand même les notifications Slack une fois activé.
Avec 3 intégrations, vous pouvez tout afficher. Avec 30, le répertoire doit répondre rapidement à une question : « Lesquelles fonctionnent, et que dois‑je faire ensuite ? » La meilleure approche est de séparer la lecture rapide de l'action.
Gardez la vue liste axée sur des décisions rapides. Poussez les contrôles lourds dans une page de détail derrière un seul bouton « Manage ».
Dans la liste, affichez seulement ce qui justifie le clic suivant :
L'anatomie de la carte compte parce qu'elle crée une mémoire musculaire. L'action primaire doit toujours signifier « l'étape suivante » selon l'état : Connect pour du neuf, Continue setup pour partiel, Reconnect quand l'auth a expiré, et Manage quand tout est sain. Évitez deux boutons primaires tout aussi visibles sur chaque carte : ça rend la page bruyante.
Exemples :
Les états vides doivent guider sans déverser un manuel :
Cela garde la page calme à 30 intégrations parce que chaque carte répond : qu'est‑ce que c'est, est‑ce ok, et que faire maintenant ?
La liste oriente vers la bonne intégration. La page de détail est où l'on décide : configurer, réparer ou désactiver. Gardez la structure de la page cohérente pour chaque intégration, même si le travail backend diffère.
Commencez par un aperçu compact : nom de l'intégration, une courte description et des libellés de statut clairs (Connected, Needs attention, Disabled). Ajoutez une petite ligne « Setup progress » pour indiquer si l'utilisateur est à une étape de la fin ou au début.
Un assistant simple marche bien : 3 à 6 étapes, une étape par écran, avec « Back » toujours disponible. Nommez les étapes en langage clair (Connect account, Choose workspace, Pick data to sync, Confirm). Si une étape propose des choix optionnels, signalez‑les comme optionnels.
Si la configuration peut être mise en pause, dites‑le clairement : « Vous pouvez terminer plus tard. Nous conserverons vos choix. » Cela réduit la peur de cliquer ailleurs.
Affichez les Connections comme un petit tableau : nom du compte, connecté par (utilisateur), date de création, et dernier sync.
Pour le « prochain sync », évitez des promesses que vous ne pouvez pas tenir (horaires exacts). Utilisez un libellé fiable comme « Next sync : scheduled soon » ou « Next sync : within the next hour », selon ce que votre système peut garantir.
Gardez les actions risquées hors du chemin principal. Placez les actions primaires en haut (Continue setup, Reconnect). Placez Disable et Disconnect dans une section « Danger zone » distincte en bas avec une courte explication d'impact. Si vous supportez des rôles, indiquez‑le en une phrase (« Seuls les admins peuvent disconnect »).
Ajoutez un petit journal d'activité : événements récents (connected, token refreshed, sync failed), horodatages et un court message d'erreur que les utilisateurs peuvent copier dans un ticket support.
Ajouter une intégration est plus simple lorsque vous la traitez comme un petit produit. Il faut une fiche catalogue, une méthode de connexion, un endroit pour stocker la connection et des résultats clairs de succès/échec.
Ajoutez l'intégration à votre catalogue afin qu'elle apparaisse dans le répertoire avant même qu'on la connecte. Incluez un nom clair, une courte description, une icône et une ou deux catégories (Messaging, Payments). Écrivez les attentes de configuration en termes simples, comme « Connect an account » et « Choose a workspace ». Définissez aussi ce que l'intégration demandera plus tard (scopes OAuth, champs requis, fonctionnalités supportées).
Choisissez le mode de connexion le plus simple qui correspond au fournisseur :
Quand l'utilisateur termine le flux, créez un enregistrement Connection lié à son workspace ou compte, pas seulement à l'utilisateur. Stockez les identifiants en sécurité (chiffrement au repos et éviter d'afficher le secret complet). Sauvegardez les éléments utiles pour le support : provider account ID, date de création, qui a connecté et permissions accordées.
Exécutez un test simple immédiatement (pour Stripe : récupérer les détails du compte). Si ça passe, affichez Connected et marquez la progression comme prête. Si c'est partiellement OK (connecté mais permission manquante), marquez Needs attention et pointez la correction exacte.
Montrez un message clair, une action recommandée et un fallback sûr. Exemple : « We couldn’t reach Stripe. Check the API key or try again. » Gardez le répertoire utilisable même si une intégration est cassée.
Si vous construisez sur Koder.ai (koder.ai), vous pouvez d'abord rédiger le catalogue, le flux de configuration et les règles de statut en Planning Mode, puis générer l'UI et le backend depuis ce plan.
Les intégrations tombent en panne pour des raisons banales. Si votre répertoire ne peut pas expliquer ces raisons clairement, les utilisateurs blâment votre app et le support n'a rien pour diagnostiquer.
Regroupez les échecs en catégories qui correspondent à des correctifs réels : login expiré, permission manquante, outage fournisseur, limite de taux. Gardez les codes d'erreur internes détaillés, mais montrez à l'utilisateur un libellé court et compréhensible.
Quand quelque chose casse, le message doit répondre à trois choses : ce qui s'est passé, ce que l'utilisateur doit faire et ce que votre système fera ensuite. Exemple : « Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect. » C'est plus calme et actionnable qu'une erreur API brute.
Les retries automatiques uniquement quand l'utilisateur ne peut rien faire :
Les statuts deviennent périmés si vous ne les rafraîchissez pas. Ajoutez un job de vérification léger qui confirme périodiquement que les tokens fonctionnent toujours, que le dernier sync a eu lieu et que le badge du répertoire reflète la réalité.
Conservez un petit historique d'événements par install. Pas besoin de logs complets, juste des indices : horodatage, événement (« token refreshed », « sync failed »), raison courte et qui l'a déclenché (utilisateur ou système). Ajoutez un champ de notes interne pour que le support enregistre les actions et raisons.
Un répertoire devient vite désordonné après quelques apps. L'objectif : aider les gens à trouver ce dont ils ont besoin en quelques secondes et repérer les problèmes sans ouvrir chaque carte.
Commencez par une recherche basique sur le nom de l'intégration et la catégorie. La plupart des utilisateurs tapent ce qu'ils connaissent déjà (« Slack », « Stripe »), donc la correspondance sur le nom importe plus que le classement sophistiqué. La recherche par catégorie aide quand ils connaissent seulement la fonction (payments, messaging).
Les filtres doivent refléter l'intention réelle. Trois filtres couvrent souvent la plupart des cas :
Pour organiser la liste, choisissez un regroupement principal et tenez‑vous y. Le regroupement par catégorie marche bien à de grands nombres (CRM, Payments, Messaging). La popularité est utile si elle reflète vraiment votre base d'utilisateurs. Un défaut pratique : afficher d'abord les plus utilisés, puis grouper le reste par catégorie.
Prévoyez aussi un plan pour « tout le monde ne doit pas voir tout ». Si une intégration est derrière un feature flag ou un niveau d'offre, soit cachez‑la pour la plupart, soit affichez‑la désactivée avec une raison courte comme « Business plan ». Évitez une page pleine de cartes grises — ça donne l'impression d'un écran cassé.
Gardez les performances réactives en traitant liste et détail comme des chargements séparés. Paginer ou virtualiser la liste pour ne pas rendre 30 cartes lourdes à la fois, et chargez les détails à la demande quand l'utilisateur ouvre une intégration. Le répertoire peut afficher des champs résumés (Slack: Connected, Google: Needs attention, Stripe: Not set up) tandis que la page de détail récupère l'historique complet de connection.
Imaginez une app workspace appelée Pinework. Elle a deux rôles : Admin et Member. Les Admins peuvent connecter des outils et modifier les réglages. Les Members peuvent utiliser les outils connectés mais ne peuvent pas les ajouter ou les retirer.
Dans le répertoire d'intégrations de Pinework, chaque carte montre un libellé clair (Connected, Needs setup, Error), une courte ligne « à quoi ça sert » et une progression comme « 2 sur 3 étapes ». Les gens voient ce qui marche et ce qui est en attente sans cliquer partout.
Slack sert aux notifications. Un Admin ouvre Slack et voit : Statut : Connected, Setup : « 3 sur 3 étapes ». Les Members voient Slack aussi, mais l'action principale est désactivée et indique « Ask an Admin to manage ». Si Slack se déconnecte, les Members voient la panne mais pas les contrôles de reconnexion.
Google sert pour les calendriers. Pinework supporte deux départements, donc il permet plusieurs connections. La carte Google affiche : Statut : Connected (2 accounts). En dessous, une courte ligne liste « Marketing Calendar » et « Support Calendar ». La configuration peut être complète, et la page de détail montre deux connections distinctes pour qu'un Admin puisse révoquer une seule.
Stripe sert à la facturation. Un scénario courant : le compte est connecté, mais les webhooks ne sont pas terminés. La carte affiche : Statut : Needs setup, Progress : « 2 sur 3 étapes », avec un avertissement « Payments may not sync ». La vue détail indique explicitement l'étape restante :
Cela évite la douloureuse situation « ça paraît connecté mais rien ne marche ».
Un répertoire d'intégrations casse souvent quand une app passe de quelques intégrations à des dizaines. Les problèmes ne sont pas souvent « très techniques ». Ce sont des erreurs de libellés et de modélisation qui embrouillent les gens au quotidien.
Un souci courant est de confondre « installé » et « connecté ». Installed signifie généralement « disponible dans votre workspace ». Connected signifie que de vrais identifiants existent et que les données peuvent circuler. Quand ces notions se mélangent, les utilisateurs cliquent sur une intégration qui semble prête et tombent sur une impasse.
Autre erreur : inventer trop de statuts. On commence simple, puis on ajoute les cas limites : pending, verifying, partial, paused, degraded, blocked, expiring, etc. Avec le temps ces labels dérivent parce que personne ne les maintient. Gardez un petit ensemble lié à des vérifications réelles : Not connected, Connected, Needs attention.
Les permissions cachées posent aussi problème. Quelqu'un connecte un compte, puis découvre plus tard que l'intégration avait un accès beaucoup plus large que prévu. Présentez les scopes clairement avant l'étape finale « Connect » et réaffichez‑les sur la page de détail pour que les admins puissent auditer.
Beaucoup d'apps ont besoin de multiples connections : deux workspaces Slack, plusieurs comptes Stripe, ou un compte Google partagé plus des comptes personnels. Si vous codez « une intégration = une connection », vous finirez avec des contournements moches.
Prévoyez :
Gardez la vue liste légère. Quand vous la surchargez de logs, de mappings de champs et de longues descriptions, la lecture ralentit. Utilisez la liste pour le nom, l'objectif court et la progression. Mettez l'historique et les réglages avancés sur la page de détail.
Un répertoire d'intégrations évolutif tient à un modèle simple et une UI honnête. Si les utilisateurs peuvent répondre rapidement à trois questions, le système paraît prévisible : quoi est connecté, quoi est cassé, et que faire ensuite ?
Checklist avant mise en production :
Ensuite, choisissez trois intégrations que vous connaissez bien et modélisez‑les de bout en bout : un outil de chat (OAuth), une connexion de type Google (OAuth avec scopes), et un outil de paiements (API key + webhooks). Si votre modèle peut exprimer les trois sans cas spéciaux, il s'étendra généralement bien jusqu'à 30.
Traitez la page comme un panneau de contrôle, pas comme une page marketing. Chaque carte doit rapidement indiquer à quoi sert l'intégration, si elle fonctionne maintenant, et la seule action suivante que l'utilisateur doit effectuer. Si les utilisateurs doivent cliquer juste pour savoir « est‑ce connecté ? », le répertoire semblera peu fiable au fur et à mesure qu'il grandit.
Une règle simple : une carte doit répondre « qu'est‑ce que c'est », « est‑ce sain » et « que faire maintenant ». Cela signifie généralement un nom et une courte description, un statut avec un horodatage récent (dernier sync ou dernière vérification) et un bouton primaire qui change selon l'état. Cachez le reste derrière « Manage » pour garder la lecture rapide.
Séparez ce que vous proposez de ce qu'un espace de travail a activé et des identifiants effectifs. Utilisez une Integration (entrée du catalogue globale), une Install (activée dans un workspace) et une Connection (compte OAuth réel, clé API ou webhook). Cela évite le désordre courant où « installé » et « connecté » se confondent.
Parce que les équipes réelles ont souvent besoin de plusieurs comptes externes pour le même fournisseur. Marketing et Support peuvent connecter des calendriers Google différents, ou une entreprise peut avoir plusieurs comptes Stripe. Modéliser plusieurs Connections sous une même Install garde le répertoire propre tout en permettant aux admins de gérer chaque compte individuellement depuis la page de détail.
Utilisez un petit ensemble de libellés faciles à maintenir, comme Not set up, In progress, Connected, Needs attention et Disabled. Dérivez ces libellés à partir de faits vérifiables (validité du token, étapes de configuration requises complétées, dernier sync réussi) pour éviter des badges périmés qui restent rouges après correction.
Faites de la progression une courte liste de contrôle : étapes requises et étapes optionnelles. Stockez la définition des étapes par intégration et les résultats par install, afin que l'interface affiche par exemple « 2 des 3 étapes requises complétées ». L'utilisateur doit toujours voir l'étape requise suivante sans fouiller.
Commencez par une règle de rôles simple qui s'applique partout, puis ajoutez une vérification supplémentaire uniquement pour les intégrations sensibles. Dans beaucoup de produits : les Admins peuvent tout configurer, les Managers peuvent configurer la plupart des outils, et les Members peuvent utiliser les outils activés mais ne peuvent pas connecter ni modifier. Pour paiements ou paie, ajoutez un simple drapeau « billing/payments admin » plutôt que de créer un nouveau rôle complexe.
Conservez la configuration visible par l'utilisateur comme des données normales, mais stockez les secrets (tokens de refresh OAuth, clés API) dans un coffre de secrets ou des champs chiffrés avec contrôles d'accès stricts. N'enregistrez pas de secrets bruts, codes d'autorisation ou payloads de webhooks dans les logs ; loggez des références (connection_id) et des métadonnées sûres. Cela réduit les risques et facilite la conformité et le support.
Affichez un message d'erreur qui dit ce qui s'est passé, ce que l'utilisateur doit faire ensuite et ce que votre système fera automatiquement. Les tentatives automatiques doivent être limitées aux problèmes que l'utilisateur ne peut pas corriger (panne du fournisseur, erreurs réseau). Pour une auth expirée ou des permissions manquantes, arrêtez les retries et faites de « Reconnect » ou « Fix permissions » l'action principale.
Gardez la recherche simple : nom du fournisseur d'abord, puis catégorie. Ajoutez des filtres pratiques : Connected, Needs attention, Not set up, afin que les gens trouvent rapidement les problèmes. Si vous utilisez Koder.ai, rédigez d'abord les champs du catalogue, les règles de statut et les étapes de configuration en Planning Mode pour que l'UI et le backend générés restent cohérents en ajoutant des intégrations.
Traitez l'ajout d'une intégration comme un petit produit : une fiche catalogue, une méthode de connexion, un endroit pour stocker la connection et des résultats clairs pour succès ou échec. Testez la connexion immédiatement et affichez Connected ou Needs attention avec une action recommandée. Cela évite l'état « relié mais ça ne marche pas ». (Note : Koder.ai et koder.ai sont des exemples de plateformes mentionnées en contexte.)
