10 दिस॰ 2025·8 मिनट
3 से 30 ऐप्स तक स्केल करने वाली इंटीग्रेशन डायरेक्टरी डिजाइन
सरल डेटा मॉडल, स्पष्ट स्टेटस, अनुमतियाँ और सेटअप प्रोग्रेस UI के साथ एक इंटीग्रेशन डायरेक्टरी डिजाइन करें जो 3 से 30 इंटीग्रेशन तक स्केल करे।
सरल डेटा मॉडल, स्पष्ट स्टेटस, अनुमतियाँ और सेटअप प्रोग्रेस UI के साथ एक इंटीग्रेशन डायरेक्टरी डिजाइन करें जो 3 से 30 इंटीग्रेशन तक स्केल करे।
लोग एक इंटीग्रेशन डायरेक्टरी केवल एक कारण से खोलते हैं: टूल्स को जोड़ना और उन्हें हर दिन सोचे बिना काम करते रखना। यदि स्क्रीन यूज़र को यह अंदाज़ा लगाने पर मजबूर कर दे कि क्या कनेक्टेड है, क्या टूटा है, या अगला क्या क्लिक करना है, तो भरोसा जल्दी घटता है।
3 इंटीग्रेशन के साथ, लोगो का एक साधारण ग्रिड काम कर सकता है। 30 के साथ, वह ढह जाता है: लोग स्कैन करना बंद कर देते हैं, सपोर्ट टिकट बढ़ते हैं, और “Connect” बटन जाल बन जाता है क्योंकि हर इंटीग्रेशन अलग स्थिति में हो सकता है।
हर इंटीग्रेशन कार्ड (या रो) को एक नज़र में तीन सवालों के जवाब देने चाहिए:
ज्यादातर भ्रम ऐसे एज केस से आता है जो असली टीम्स में लगातार होते हैं। कोई Google को पर्सनल अकाउंट से कनेक्ट कर देता है बजाय कंपनी वाले। Stripe टोकन एक्सपायर हो जाता है और बिलिंग सिंक रुक जाती है। Slack वर्कस्पेस कनेक्ट है, पर ज़रूरी चैनल स्कोप नहीं दिया गया, तो सेटअप “आधा पूरा” रहता है जबकि UI ठीक दिखता है।
एक अच्छी स्क्रीन इन स्थितियों को स्पष्ट बनाती है। सिर्फ “Connected” दिखाने की बजाय कुछ ऐसा दिखाएँ: “Connected (needs permission)” या “Connected to: [email protected],” और कार्ड पर अगला कदम रखें। इससे यूज़र अनुमान लगाने से बचते हैं और सूची बढ़ने पर भी संभालने योग्य रहती है।
इंटीग्रेशन डायरेक्टरी को स्केल करने का सबसे सरल तरीका है अलग करना:
यह 3 इंटीग्रेशन पर पठनीय रहता है और 30 पर भी काम करता है।
इंटीग्रेशन कैटलॉग एंट्री है। यह ग्लोबल है, किसी वर्कस्पेस से जुड़ा नहीं है।
इंस्टॉल उस बात का प्रतिनिधित्व करता है कि किसी वर्कस्पेस ने वह इंटीग्रेशन सक्षम किया है (उदाहरण: “Slack Workspace A के लिए ऑन है”)।
कनेक्शन एक असली बाहरी अकाउंट या क्रेडेंशियल को दर्शाता है (उदाहरण: “Slack workspace X via OAuth” या “Stripe account Y via API key”). एक Install के पास कई Connections हो सकते हैं।
स्केल करने के लिए जो फील्ड्स आम तौर पर काम करते हैं उनकी एक न्यूनतम सूची:
इंस्टॉल या कनेक्शन पर यूज़र-देखने योग्य कॉन्फ़िग (चयनित चैनल, वेबहुक URL उपनाम, enabled events) को सामान्य डेटा के रूप में स्टोर करें। सीक्रेट्स (OAuth refresh tokens, API keys, signing secrets) केवल एक सिक्रेट स्टोर या एन्क्रिप्टेड फ़ील्ड में रखें और सख़्त एक्सेस कंट्रोल लागू करें।
सीक्रेट्स, पूर्ण ऑथORIZATION कोड, या कच्चे वेबहुक पेलोड्स को लॉग में न डालें। अगर कुछ लॉग करना ज़रूरी है, तो संदर्भ (connection_id) और सुरक्षित मेटाडेटा (HTTP स्टेटस, एरर कोड) लॉग करें।
OAuth, API keys, और वेबहुक्स में लचीलापन बनाए रखने के लिए auth-विशिष्ट फ़ील्ड्स Connection में रखें (टोकन मेटाडेटा vs की फ़िंगरप्रिंट vs वेबहुक सत्यापन स्टेटस)। UI-फेसिंग स्टेट (enabled और setup progress) को Install पर रखें।
लोग इंटीग्रेशन डायरेक्टरी खोलते समय तीन चीज़ें जल्दी जानना चाहते हैं: क्या यह काम कर रहा है, सेटअप कितना पूरा है, और अगला कदम क्या है। अगर आपके स्टेटस शब्द अस्पष्ट हैं, तो सपोर्ट टिकट बढ़ेंगे और भरोसा घटेगा।
किसी छोटे स्टेटस सेट से शुरू करें जिसे आप वर्षों तक बनाए रख सकें:
स्टोर किए गए लेबल्स की बजाय व्युत्पन्न (derived) स्टेटस को प्राथमिकता दें। स्टोर किए हुए लेबल्स ड्रिफ्ट हो जाते हैं: कोई समस्या ठीक कर देता है, पर बैज लाल ही बना रहता है। Derived status उन तथ्यों से गणना करें जो आप पहले से ट्रैक करते हैं, जैसे टोकन वैध है या नहीं, आवश्यक सेटअप स्टेप्स पूरे हैं या नहीं, और क्या किसी एडमिन ने इंटीग्रेशन को पॉज़ किया है। अगर आप कुछ स्टोर करते हैं तो अंतिम लेबल नहीं, बल्कि उन बुनियादी फैक्ट्स को स्टोर करें (last successful sync, last error code)।
सेटअप प्रोग्रेस छोटे चेकलिस्ट के रूप में सबसे अच्छा काम करता है, जिसमें आवश्यक और वैकल्पिक के बीच स्पष्ट विभाजन हो। इसे स्टेप डेफिनिशन (प्रति इंटीग्रेशन स्थिर) और स्टेप रिज़ल्ट्स (प्रति इंस्टॉल) के रूप में मॉडल करें।
उदाहरण: Slack के लिए आवश्यक स्टेप्स हो सकते हैं “Authorize workspace” और “Select channels,” और एक वैकल्पिक स्टेप हो सकता है “Enable message previews.” UI “2 of 3 required steps complete” दिखा सकता है जबकि वैकल्पिक आइटम खोजने योग्य रहते हैं बिना पूरा ब्लॉक किए।
एक ही इंटीग्रेशन के नीचे कई कनेक्शंस सूची को गड़बड़ कर सकते हैं अगर आप इसके लिए योजना नहीं बनाते। एक कार्ड प्रति इंटीग्रेशन रखें, कनेक्शन काउंट दिखाएँ, और स्थिति को ईमानदारी से रोल-अप करें। अगर कोई भी कनेक्शन टूटा है, तो “Needs attention” दिखाएँ और एक हिंट दें जैसे “1 of 4 workspaces needs re-auth.” ओवरव्यू साफ़ रहता है, पर हकीकत भी दिखती है।
इंटीग्रेशन अनुमतियाँ तब जटिल हो जाती हैं जब हर चीज़ को एक स्विच की तरह माना जाता है। इसे स्पष्ट रखने के लिए अलग करें:
एक हल्का रोल चेक रखें जो हर जगह लागू हो। कई ऐप्स के लिए तीन रोल अक्सर काफी हैं: Admin, Manager, और Member। Admins सब कर सकते हैं। Managers अपनी टीम के लिए अधिकांश इंटीग्रेशन सेटअप कर सकते हैं। Members पहले से सक्षम इंटीग्रेशन का उपयोग कर सकते हैं, पर सेटिंग्स बदल नहीं सकते।
फिर केवल वहीं पर-इंटीग्रेशन परमिशन फ़्लैग जोड़ें जहाँ इसकी ज़रूरत है। ज़्यादातर इंटीग्रेशन (कैलेंडर, चैट) डिफ़ॉल्ट रोल नियम फॉलो कर सकते हैं। सेंसिटिव वाले (payments, payroll, exports) को एक अतिरिक्त चेक चाहिए जैसे “Payments admin” या “Billing manager.” इसे एक साधारण बूलियन के रूप में Install पर रखें, किसी नए रोल सिस्टम के बजाय।
एक ऐसा मैप जो पठनीय रहे:
ऑडिट को भारी नहीं बनाना चाहिए, पर मौजूद होना चाहिए। पर्याप्त ट्रैक रखें ताकि सपोर्ट और सुरक्षा सवालों का जवाब जल्दी मिल सके: किसने कनेक्ट किया, कब क्रेडेंशियल बदले गए, और किसने इसे डिसेबल किया। डिटेल पेज पर 5 से 20 हालिया इवेंट्स का “Activity” पैनल आमतौर पर पर्याप्त होता है।
उदाहरण: Stripe सभी के लिए दिखाई दे सकता है, पर सिर्फ Admins (या “Billing manager” वाले यूज़र) ही इसे कनेक्ट कर सकें, की रोटेट कर सकें, या payouts डिसेबल कर सकें। Slack Managers को कनेक्ट करने दे सकता है, जबकि Members सक्षम होने पर नोटिफिकेशन प्राप्त कर सकते हैं पर सेटिंग बदल नहीं सकते।
3 इंटीग्रेशन पर आप सब कुछ दिखा सकते हैं। 30 पर, डायरेक्टरी को एक तेज़ सवाल का जवाब देना होगा: “कौन काम कर रहे हैं, और अगला क्या करना है?” सबसे साफ़ तरीका है स्कैनिंग को करने से अलग करना।
लिस्ट व्यू को तेज़ निर्णयों पर केंद्रित रखें। भारी कंट्रोल्स को एक “Manage” बटन के पीछे डिटेल पेज पर रखें।
लिस्ट में केवल वही दिखाएँ जो अगले क्लिक का समर्थन करे:
कार्ड का अनाटॉमी मायने रखता है क्योंकि यह मसल मेमोरी बनाता है। प्राइमरी एक्शन हमेशा “अगला कदम” दर्शाना चाहिए: नए के लिए Connect, आंशिक के लिए Continue setup, auth एक्सपायर होने पर Reconnect, और सब कुछ ठीक होने पर Manage। हर कार्ड पर दो बराबर जोर वाले बटनों से बचें — यह पेज को शोरगुल भरा बनाता है।
उदाहरण:
खाली अवस्थाएँ गाइड करें बिना एक मैनुअल फेंके:
इससे 30 इंटीग्रेशन पर भी पेज शांत रहता है क्योंकि हर कार्ड जवाब देता है: यह क्या है, क्या यह ठीक है, और अब मैं क्या करूं?
डायरेक्टरी सूची लोगों को सही इंटीग्रेशन तक ले जाती है। डिटेल पेज वह जगह है जहां वे फैसला करते हैं: सेटअप करें, ठीक करें, या बंद कर दें। पेज स्ट्रक्चर हर इंटीग्रेशन में सुसंगत रखें, भले ही बैकएंड अलग हो।
संकुचित ओवरव्यू से शुरू करें: इंटीग्रेशन नाम, एक-लाइन डिस्क्रिप्शन, और स्पष्ट स्टेटस लेबल (Connected, Needs attention, Disabled). एक छोटा “Setup progress” लाइन जोड़ें ताकि यूज़र जानें कि वे कितने चरण दूर हैं।
एक सरल विज़ार्ड अच्छा काम करता है: 3–6 स्टेप्स, एक स्क्रीन पर एक स्टेप, और “Back” हमेशा उपलब्ध। स्टेप्स को सरल भाषा में नाम दें (Connect account, Choose workspace, Pick data to sync, Confirm)। यदि किसी स्टेप में वैकल्पिक विकल्प हैं तो उन्हें optional लेबल करें बजाय छुपाने के।
अगर सेटअप रोका जा सके, तो स्पष्ट कहें: “आप बाद में पूरा कर सकते हैं। हम आपकी पसंद बचाएंगे।” इससे यूज़र के क्लिक करने का डर कम होता है।
Connections को एक छोटी टेबल के रूप में दिखाएँ: अकाउंट नाम, किसने कनेक्ट किया (यूज़र), बनाया कब, और आख़िरी सिंक।
“Next sync” के लिए ऐसे दावे न करें जिन्हें आप पूरा नहीं कर सकते (जैसे सटीक समय)। ऐसे शब्दों का उपयोग करें जिन्हें आप टिकाऊ रूप से सपोर्ट कर सकें, जैसे “Next sync: scheduled soon” या “Next sync: within the next hour,” जो आपकी सिस्टम की गारंटी के अनुरूप हों।
जोखिम भरे एक्शन्स को मुख्य रास्ते से दूर रखें। प्रमुख एक्शन्स ऊपर रखें (Continue setup, Reconnect). Disable और Disconnect को पेज के नीचे “Danger zone” सेक्शन में रखें और प्रभाव का संक्षिप्त वर्णन दें। यदि आप रोल्स सपोर्ट करते हैं, तो एक वाक्य में बताएं (जैसे, “Only admins can disconnect”).
एक छोटा एक्टिविटी लॉग जोड़ें: हालिया इवेंट्स (connected, token refreshed, sync failed), टाइमस्टैम्प्स, और एक संक्षिप्त एरर संदेश जिसे यूज़र सपोर्ट टिकट में कॉपी कर सके।
इंटीग्रेशन जोड़ना आसान होता है जब आप उसे एक छोटे प्रोडक्ट की तरह ट्रीट करते हैं। इसे एक लिस्टिंग चाहिए, कनेक्ट करने का तरीका, कनेक्शन स्टोर करने की जगह, और सफलता या विफलता के स्पष्ट परिणाम।
इंटीग्रेशन को अपने कैटलॉग में जोड़ें ताकि वह डायरेक्टरी में तब भी दिखाई दे जब तक किसी ने उसे कनेक्ट न किया हो। स्पष्ट नाम, छोटा विवरण, आइकन, और एक या दो कैटेगरी (Messaging, Payments) शामिल करें। सादे शब्दों में सेटअप अपेक्षाएँ लिखें, जैसे “एक अकाउंट कनेक्ट करें” और “एक वर्कस्पेस चुनें।” यह वह जगह भी है जहाँ आप बाद में आवश्यकता बताएँगे (OAuth scopes, required fields, supported features)।
प्रोवाइडर के अनुरूप सबसे सरल कनेक्शन चुनें:
जब यूज़र फ्लो पूरा करता है, तो उनके वर्कस्पेस/अकाउंट से जुड़ा एक Connection रिकॉर्ड बनाएं, सिर्फ यूज़र से नहीं। क्रेडेंशियल्स सुरक्षित रखें (रेस्ट पर एन्क्रिप्ट करें और पूर्ण सीक्रेट फिर न दिखाएँ)। सपोर्ट के लिए आवश्यक बेसिक्स सेव करें: प्रोवाइडर अकाउंट ID, बनाया कब, किसने कनेक्ट किया, और किन परमिशन्स की इजाज़त दी गई।
तुरंत एक साधारण टेस्ट चलाएँ (Stripe के लिए: अकाउंट डिटेल्स फेच करें)। अगर पास हुआ तो Connected दिखाएँ और प्रोग्रेस तैयार मार्क करें। अगर आंशिक रूप से पास हुआ (कनेक्ट तो हुआ पर परमिशन गायब), तो Needs attention मार्क करें और सटीक फ़िक्स पॉइंट करें।
एक स्पष्ट संदेश, एक सिफारिश की हुई कार्रवाई, और एक सुरक्षित फॉलबैक दिखाएँ। उदाहरण: “We couldn’t reach Stripe. Check the API key or try again.” एक इंटीग्रेशन टूटने पर भी डायरेक्टरी उपयोग करने योग्य रखें।
अगर आप Koder.ai (koder.ai) पर बना रहे हैं, तो आप Planning Mode में पहले कैटलॉग, सेटअप फ्लो, और स्टेटस नियम ड्राफ्ट कर सकते हैं, फिर उस प्लान से UI और बैकएंड जनरेट कर सकते हैं।
इंटीग्रेशन अक्सर नीरस कारणों से फेल होते हैं। अगर डायरेक्टरी उन कारणों को साफ़ तौर पर नहीं बता पाती, तो यूज़र आपकी ऐप को दोष देते हैं और सपोर्ट के पास काम करने के लिए कुछ नहीं रहता।
फेल्यर्स को उन बकेट्स में ग्रुप करें जिनसे असली फिक्स्स जुड़ी हों: लॉगिन एक्सपायर, मिसिंग परमिशन, प्रोवाइडर आउटेज, या रेट लिमिट। आंतरिक एरर कोड्स डिटेल्ड रखें, पर यूज़र को एक छोटा और समझने योग्य लेबल दिखाएं।
जब कुछ टूटता है, संदेश तीन चीज़ों का जवाब दे: क्या हुआ, यूज़र को क्या करना चाहिए, और आपकी सिस्टम अगले में क्या करेगी। उदाहरण: “Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.” यह एक कच्चे API एरर से ज़्यादा शांत और actionable है।
ऑटो-रिट्राई सिर्फ़ उन मामलों में करें जिन्हें यूज़र स्वयं ठीक नहीं कर सकता। एक साधारण नियम सेट काफ़ी होता है:
स्टेटस तब पुराना दिखने लगते हैं जब आप उन्हें रिफ्रेश न करें। एक हल्का हेल्थ चेक जॉब जोड़ें जो समय-समय पर टोकन की वैधता, आख़िरी सिंक का रन होना, और डायरेक्टरी बैज का मिलान चेक करे।
प्रति इंस्टॉल एक छोटा इवेंट हिस्ट्री रखें। आपको पूरा लॉग नहीं चाहिए — बस पर्याप्त breadcrumbs: टाइमस्टैम्प, इवेंट (“token refreshed”, “sync failed”), छोटा कारण, और किसने ट्रिगर किया (यूज़र या सिस्टम)। एक internal-only notes फ़ील्ड रखें ताकि सपोर्ट यह रिकॉर्ड कर सके कि उन्होंने क्या बदला और क्यों।
डायरेक्टरी एक बार कुछ ऐप्स पार कर जाए तो जल्दी गड़बड़ हो जाती है। लक्ष्य सरल है: लोगों को सेकंडों में वो मिल जाए जो उन्हें चाहिए, और समस्याएँ बिना हर कार्ड खोले ही दिख जाएँ।
इंटीग्रेशन नाम और कैटेगरी पर बेसिक सर्च से शुरू करें। ज़्यादातर यूज़र वही टाइप करते हैं जो उन्हें पहले से पता होता है (“Slack”, “Stripe”), इसलिए नाम मैचिंग fancy रैंकिंग से ज़्यादा मायने रखती है। कैटेगरी सर्च तब काम आती है जब उन्हें सिर्फ काम पता हो (payments, messaging)।
फ़िल्टर्स को वास्तविक इरादे के अनुरूप रखें। ये तीन अक्सर अधिकांश उपयोग केस कवर करते हैं:
लिस्ट व्यवस्थित करने के लिए एक प्राथमिक ग्रुपिंग चुनें और उसी पर टिके रहें। उच्च संख्या पर category grouping अच्छा काम करता है (CRM, Payments, Messaging)। लोकप्रियता भी उपयोगी हो सकती है, पर तभी जब वह आपके यूज़र बेस को दर्शाए न कि मार्केटिंग को। एक व्यावहारिक डिफ़ॉल्ट: सबसे ज़्यादा उपयोग वाले पहले दिखाएँ, फिर बाकी को कैटेगरी से ग्रुप करें।
यह भी तय करें कि “हर कोई सब कुछ न देखे” का साफ़ प्लान क्या होगा। अगर कोई इंटीग्रेशन फीचर फ्लैग या प्लान टियर के पीछे है, तो या तो उसे अधिकांश यूज़र्स के लिए छिपाएँ या उसे डिसेबल्ड दिखाएँ एक छोटा कारण के साथ जैसे “Business plan.” ग्रे कार्ड्स से भरा पेज दिखाना टाला जाना चाहिए — यह स्क्रीन को टूटी हुई महसूस कराता है।
प्रदर्शन तेज़ रखने के लिए लिस्ट और डिटेल को अलग लोड करें। सूची को paginate या virtualize करें ताकि आप 30 भारी कार्ड एक साथ render न करें, और डिटेल तब लोड करें जब यूज़र किसी इंटीग्रेशन को खोले। डायरेक्टरी सारांश फ़ील्ड्स दिखा सकती है (Slack: Connected, Google: Needs attention, Stripe: Not set up) जबकि डिटेल पेज पूरा कनेक्शन हिस्ट्री फ़ेच करे।
एक टीम वर्कस्पेस ऐप का कल्पना करें जिसका नाम Pinework है। इसमें दो रोल्स हैं: Admin और Member. Admins टूल कनेक्ट कर सकते हैं और सेटिंग बदल सकते हैं। Members जुड़े टूल्स का उपयोग कर सकते हैं पर जोड़ या हटाने नहीं कर सकते।
Pinework की इंटीग्रेशन डायरेक्टरी में हर कार्ड पर स्पष्ट लेबल (Connected, Needs setup, Error), एक छोटा “यह क्या करता है” लाइन, और सेटअप प्रोग्रेस जैसे “2 of 3 steps” दिखता है। लोग बिना ज्यादा क्लिक किए जान जाते हैं कि क्या काम कर रहा है और क्या बाकी है।
Slack नोटिफिकेशन के लिए उपयोग होता है। एक Admin Slack खोलता है और देखता है: Status: Connected, Setup: “3 of 3 steps.” Members भी Slack देख पाते हैं, पर मुख्य कार्रवाई disabled है और लिखता है “Ask an Admin to manage.” अगर Slack disconnect हो जाता है, Members भी देख सकते हैं कि क्या टूटा पर reconnect कंट्रोल्स नहीं कर सकते।
Google कैलेंडर के लिए Pinework दो डिपार्टमेंट्स सपोर्ट करता है, इसलिए कई कनेक्शंस की अनुमति देता है। Google कार्ड दिखाता है: Status: Connected (2 accounts). उसके नीचे एक संक्षिप्त लाइन “Marketing Calendar” और “Support Calendar” जैसी सूची दिखती है। डिटेल पेज पर दो अलग कनेक्शंस दिखती हैं ताकि Admin सिर्फ एक को revoke कर सके।
Stripe बिलिंग के लिए इस्तेमाल होता है। एक आम आंशिक सेटअप यह है: अकाउंट कनेक्ट है, पर वेबहुक्स पूरा नहीं हुए। कार्ड दिखाता है: Status: Needs setup, Progress: “2 of 3 steps,” साथ में चेतावनी “Payments may not sync.” डिटेल व्यू बचे हुए स्टेप को स्पष्ट करता है:
यह “लगा हुआ है कि कनेक्टेड है पर कुछ काम नहीं कर रहा” की पीड़ा टालता है।
इंटीग्रेशन डायरेक्टरी आमतौर पर तब टूटती है जब एक ऐप कुछ इंटीग्रेशन से दर्जनों तक बढ़ता है। समस्याएँ शायद बड़ी तकनीकी नहीं होतीं — वे छोटे लेबलिंग और मॉडलिंग की गलतियाँ होती हैं जो रोज़ लोगों को भ्रमित करती हैं।
एक आम समस्या “installed” और “connected” को मिलाना है। Installed आम तौर पर मतलब है “आपके वर्कस्पेस में उपलब्ध।” Connected मतलब असल क्रेडेंशियल मौजूद हैं और डेटा बह सकता है। जब ये दो मिल जाते हैं, तो यूज़र एक ऐसा इंटीग्रेशन क्लिक करता है जो तैयार दिखता है और एक डेड एंड आता है।
एक और गलती बहुत सारे स्टेटस स्टेट्स बनाना है। टीमें एक साधारण बैज से शुरू कर देती हैं, फिर एज केस जोड़ती जाती हैं: pending, verifying, partial, paused, degraded, blocked, expiring, और भी बहुत कुछ। समय के साथ वे लेबल वास्तविकता से अलग हो जाते हैं क्योंकि कोई उन्हें सुसंगत नहीं रखता। एक छोटा सेट रखें जो आप वाकई चेक कर सकें, जैसे Not connected, Connected, Needs attention।
छुपी परमिशन्स भी परेशानी खड़ी करती हैं। कोई अकाउंट कनेक्ट कर देता है, फिर बाद में पता चलता है कि इंटीग्रेशन ने अपेक्षा से ज़्यादा एक्सेस मांगा। अंतिम “Connect” स्टेप से पहले स्कोप को स्पष्ट दिखाएँ, और डिटेल पेज पर भी दिखाएँ ताकि एडमिन ऑडिट कर सकें।
कई ऐप्स को कई कनेक्शंस चाहिए: दो Slack वर्कस्पेस, कई Stripe अकाउंट्स, या साझा Google अकाउंट के साथ पर्सनल अकाउंट। अगर आप “एक इंटीग्रेशन = एक कनेक्शन” हार्डकोड कर देंगे तो बाद में बदसूरत वर्कअराउंड बनेंगे।
योजना बनाएं:
लिस्ट व्यू हल्का रखें। जब आप इसे लॉग्स, फ़ील्ड मैपिंग्स, और लंबे विवरणों से भर देते हैं, तो स्कैनिंग धीमी हो जाती है। सूची में नाम, छोटा उद्देश्य, और सेटअप प्रोग्रेस रखें। इतिहास और उन्नत सेटिंग्स डिटेल पेज पर रखें।
एक स्केलेबल इंटीग्रेशन डायरेक्टरी एक सरल मॉडल और ईमानदार UI पर आती है। अगर यूज़र तीन सवालों के जल्दी जवाब पा सकें तो सिस्टम भविष्यवाणीयोग्य लगता है: क्या कनेक्टेड है, क्या टूटा है, और अगला क्या करना है?
शिप करने से पहले चेकलिस्ट:
अगला कदम: तीन इंटीग्रेशंस चुनें जिन्हें आप अच्छी तरह जानते हैं और उन्हें end-to-end मॉडल करें: एक चैट टूल (OAuth), एक Google-शैली अकाउंट कनेक्शन (OAuth with scopes), और एक पेमेंट टूल (API key + वेबहुक्स)। अगर आपका मॉडल बिना स्पेशल केसेस के इन तीनों को व्यक्त कर सके, तो यह आम तौर पर 30 तक स्केल कर जाएगा।
इसे कंट्रोल पैनल की तरह ट्रीट करें, मार्केटिंग पेज की तरह नहीं। हर कार्ड को जल्दी बताना चाहिए कि इंटीग्रेशन किस काम का है, क्या अभी यह काम कर रहा है, और यूज़र को अगला एक्शन क्या लेना चाहिए। अगर यूज़र को सिर्फ ये जानने के लिए क्लिक करना पड़े कि “क्या यह कनेक्टेड है?”, तो डायरेक्टरी बड़ी होने पर भरोसा घट जाएगा।
एक साधारण नियम: हर कार्ड को बताना चाहिए “यह क्या है”, “क्या यह स्वस्थ है”, और “अब क्या करें।” सामान्यतः इसमें एक नाम + एक-लाइन पर्पस, हालिया टाइमस्टैम्प के साथ एक स्टेटस, और एक प्राइमरी बटन होगा जो स्थिति के अनुसार बदलता है। बाक़ी सब कुछ “Manage” के पीछे रखें ताकि स्कैनिंग तेज़ रहे।
यह अलग करने से आपको पता चलता है कि आप क्या ऑफर करते हैं, किस वर्कस्पेस ने क्या इनेबल किया है, और कौन से क्रेडेंशियल असल में मौजूद हैं। एक ग्लोबल Integration (कैटलॉग एंट्री), एक Install (वर्कस्पेस में सक्षम), और एक Connection (वास्तविक OAuth अकाउंट/API की/वेबहुक) रखें। इससे अक्सर होने वाली उलझन — जहां “installed” और “connected” मिल जाते हैं — बचती है।
असली टीम्स अक्सर एक ही प्रदाता के कई अकाउंट कनेक्ट करती हैं — जैसे अलग Google कैलेंडर, कई Stripe अकाउंट। एक Install के अंदर कई Connections की अनुमति दें ताकि सूची साफ़ रहे और एडमिन अलग-अलग अकाउंट्स को डिटेल पेज से मैनेज कर सकें।
छोटी और स्थिर लेबल सेट रखें जिन्हें आप लगातार अपडेट कर सकें: Not set up, In progress, Connected, Needs attention, Disabled। इन लेबल्स को सीधे स्टोर करने के बजाए ऐसे फैक्ट्स से व्युत्पन्न करें जिन्हें आप चेक कर सकें — जैसे टोकन वैध है या नहीं, आवश्यक स्टेप्स पूरे हुए या नहीं, आख़िरी सफल सिंक कब हुआ। इससे स्टेटस पुराने होने की समस्या नहीं आएगी।
सेटअप प्रोग्रेस को छोटे चेकलिस्ट के रूप में रखें: आवश्यक स्टेप्स और वैकल्पिक स्टेप्स अलग दिखें। हर Integration के लिए स्टेप डेफिनिशन स्टोर करें और हर Install के लिए स्टेप रिज़ल्ट्स रखें, ताकि UI जैसे “2 of 3 required steps complete” दिखा सके। उपयोगकर्ता को हमेशा अगला अनमिटेड आवश्यक स्टेप दिखे।
सादा रोल रूल से शुरू करें और केवल संवेदनशील इंटीग्रेशन के लिए अतिरिक्त चेक जोड़ें। ज़्यादातर प्रोडक्ट्स में Admins सब कर सकते हैं, Managers अधिकांश टूल सेटअप कर सकते हैं, और Members सक्षम टूल्स का उपयोग कर सकते हैं पर बदल नहीं सकते। पेमेंट्स या पेरोल जैसे मामलों के लिए एक सिंगल “billing/payments admin” फ़्लैग रखें बजाय नए रोल सिस्टम के।
यूज़र-देखने वाले कॉन्फ़िग (चैनल चयन, वेबहुक URL का nickname, enabled events) सामान्य डेटा की तरह रखें। सीक्रेट्स (OAuth refresh tokens, API keys, signing secrets) केवल सिक्रेट स्टोर या एन्क्रिप्टेड फ़ील्ड में रखें और उन्हें लॉग्स में न डालें। अगर कुछ लॉग करना ज़रूरी हो, तो कनेक्शन ID जैसे संदर्भ और सुरक्षित मेटाडेटा (HTTP स्टेटस, एरर कोड) लॉग करें।
यूज़र को स्पष्ट करें कि क्या हुआ, उन्हें क्या करना चाहिए, और आपकी सिस्टम आगे क्या करेगी। retries केवल उन परिस्थितियों में करें जिन्हें यूज़र स्वयं ठीक नहीं कर सकता (प्रोवाइडर डाउन, नेटवर्क इशू)। ऑथ एक्सपायर या मिसिंग परमिशन में रीट्राई रोक दें और “Reconnect” या “Fix permissions” को प्राइमरी एक्शन बनाएं।
सर्च को सरल रखें: सबसे पहले प्रोवाइडर नाम, फिर कैटेगरी। फ़िल्टर्स उपयोगकर्ता के इरादे के अनुरूप रखें, जैसे Connected, Needs attention, और Not set up। अगर आप Koder.ai पर बना रहे हैं, तो Planning Mode में कैटलॉग फील्ड्स, स्टेटस रूल्स और सेटअप स्टेप्स ड्राफ्ट करें ताकि जेनरेटेड UI और बैकएंड एक जैसे रहें।