3 से 30 ऐप्स तक स्केल करने वाली इंटीग्रेशन डायरेक्टरी डिजाइन

इंटीग्रेशन स्क्रीन को क्या करना चाहिए (सीधी भाषा में)

लोग एक इंटीग्रेशन डायरेक्टरी केवल एक कारण से खोलते हैं: टूल्स को जोड़ना और उन्हें हर दिन सोचे बिना काम करते रखना। यदि स्क्रीन यूज़र को यह अंदाज़ा लगाने पर मजबूर कर दे कि क्या कनेक्टेड है, क्या टूटा है, या अगला क्या क्लिक करना है, तो भरोसा जल्दी घटता है।

3 इंटीग्रेशन के साथ, लोगो का एक साधारण ग्रिड काम कर सकता है। 30 के साथ, वह ढह जाता है: लोग स्कैन करना बंद कर देते हैं, सपोर्ट टिकट बढ़ते हैं, और “Connect” बटन जाल बन जाता है क्योंकि हर इंटीग्रेशन अलग स्थिति में हो सकता है।

हर इंटीग्रेशन कार्ड (या रो) को एक नज़र में तीन सवालों के जवाब देने चाहिए:

• यह क्या है? (नाम और छोटा उद्देश्य)
• क्या यह अभी सही काम कर रहा है? (स्पष्ट स्टेटस और आख़िरी चेक या आख़िरी सिंक)
• अगला क्या करना है? (Connect, Continue setup, re-auth, manage)

ज्यादातर भ्रम ऐसे एज केस से आता है जो असली टीम्स में लगातार होते हैं। कोई Google को पर्सनल अकाउंट से कनेक्ट कर देता है बजाय कंपनी वाले। Stripe टोकन एक्सपायर हो जाता है और बिलिंग सिंक रुक जाती है। Slack वर्कस्पेस कनेक्ट है, पर ज़रूरी चैनल स्कोप नहीं दिया गया, तो सेटअप “आधा पूरा” रहता है जबकि UI ठीक दिखता है।

एक अच्छी स्क्रीन इन स्थितियों को स्पष्ट बनाती है। सिर्फ “Connected” दिखाने की बजाय कुछ ऐसा दिखाएँ: “Connected (needs permission)” या “Connected to: [email protected],” और कार्ड पर अगला कदम रखें। इससे यूज़र अनुमान लगाने से बचते हैं और सूची बढ़ने पर भी संभालने योग्य रहती है।

एक सरल डेटा मॉडल: कैटलॉग vs इंस्टॉल vs कनेक्शंस

इंटीग्रेशन डायरेक्टरी को स्केल करने का सबसे सरल तरीका है अलग करना:

• आप क्या ऑफर करते हैं (कैटलॉग)
• हर वर्कस्पेस ने क्या एनेबल किया है (इंस्टॉल)
• कौन से बाहरी खाते या क्रेडेंशियल उपयोग में हैं (कनेक्शंस)

यह 3 इंटीग्रेशन पर पठनीय रहता है और 30 पर भी काम करता है।

तीन मुख्य ऑब्जेक्ट्स

इंटीग्रेशन कैटलॉग एंट्री है। यह ग्लोबल है, किसी वर्कस्पेस से जुड़ा नहीं है।

इंस्टॉल उस बात का प्रतिनिधित्व करता है कि किसी वर्कस्पेस ने वह इंटीग्रेशन सक्षम किया है (उदाहरण: “Slack Workspace A के लिए ऑन है”)।

कनेक्शन एक असली बाहरी अकाउंट या क्रेडेंशियल को दर्शाता है (उदाहरण: “Slack workspace X via OAuth” या “Stripe account Y via API key”). एक Install के पास कई Connections हो सकते हैं।

स्केल करने के लिए जो फील्ड्स आम तौर पर काम करते हैं उनकी एक न्यूनतम सूची:

• Integration: id, key ("slack"), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (संक्षिप्त टेक्स्ट), created_at
• Install: id, workspace_id, integration_id, status (enabled/disabled), setup_state (not_started/in_progress/complete), created_by, created_at, updated_at
• Connection: id, install_id, label ("Marketing Slack"), connection_status (ok/expired/error), external_account_id (अगर ज्ञात हो), scopes/permissions_granted, last_success_at, created_at

कॉन्फ़िग vs सीक्रेट्स (और क्या लीक नहीं होना चाहिए)

इंस्टॉल या कनेक्शन पर यूज़र-देखने योग्य कॉन्फ़िग (चयनित चैनल, वेबहुक 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 पर रखें।

स्टेटस और सेटअप प्रोग्रेस जो यूज़र समझ सकें

लोग इंटीग्रेशन डायरेक्टरी खोलते समय तीन चीज़ें जल्दी जानना चाहते हैं: क्या यह काम कर रहा है, सेटअप कितना पूरा है, और अगला कदम क्या है। अगर आपके स्टेटस शब्द अस्पष्ट हैं, तो सपोर्ट टिकट बढ़ेंगे और भरोसा घटेगा।

किसी छोटे स्टेटस सेट से शुरू करें जिसे आप वर्षों तक बनाए रख सकें:

• Not set up
• In progress
• Connected
• Needs attention
• Disabled

स्टोर किए गए लेबल्स की बजाय व्युत्पन्न (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 पर रखें, किसी नए रोल सिस्टम के बजाय।

एक ऐसा मैप जो पठनीय रहे:

• View: Admin, Manager, Member
• Configure: Admin, Manager (Members देख सकते हैं पर connect या edit नहीं कर सकते)
• Use: वर्कस्पेस में कोई भी जब सक्षम हो (जब तक restricted न हो)
• Sensitive override: केवल जिन उपयोगकर्ताओं के पास विशेष फ़्लैग है वे कॉन्फ़िगर या ट्रिगर कर सकें

ऑडिट को भारी नहीं बनाना चाहिए, पर मौजूद होना चाहिए। पर्याप्त ट्रैक रखें ताकि सपोर्ट और सुरक्षा सवालों का जवाब जल्दी मिल सके: किसने कनेक्ट किया, कब क्रेडेंशियल बदले गए, और किसने इसे डिसेबल किया। डिटेल पेज पर 5 से 20 हालिया इवेंट्स का “Activity” पैनल आमतौर पर पर्याप्त होता है।

उदाहरण: Stripe सभी के लिए दिखाई दे सकता है, पर सिर्फ Admins (या “Billing manager” वाले यूज़र) ही इसे कनेक्ट कर सकें, की रोटेट कर सकें, या payouts डिसेबल कर सकें। Slack Managers को कनेक्ट करने दे सकता है, जबकि Members सक्षम होने पर नोटिफिकेशन प्राप्त कर सकते हैं पर सेटिंग बदल नहीं सकते।

30 इंटीग्रेशन पर भी काम करने वाला UI लेआउट

3 इंटीग्रेशन पर आप सब कुछ दिखा सकते हैं। 30 पर, डायरेक्टरी को एक तेज़ सवाल का जवाब देना होगा: “कौन काम कर रहे हैं, और अगला क्या करना है?” सबसे साफ़ तरीका है स्कैनिंग को करने से अलग करना।

लिस्ट व्यू को तेज़ निर्णयों पर केंद्रित रखें। भारी कंट्रोल्स को एक “Manage” बटन के पीछे डिटेल पेज पर रखें।

लिस्ट में केवल वही दिखाएँ जो अगले क्लिक का समर्थन करे:

• आइकन, नाम, और एक-लाइन डिस्क्रिप्शन (लंबाई सुसंगत रखें)
• एक स्पष्ट स्टेटस पिल (Connected, Needs setup, Error, Disabled)
• एक प्राइमरी एक्शन बटन
• एक सेकेंडरी “Manage” बटन बाकी के लिए

कार्ड का अनाटॉमी मायने रखता है क्योंकि यह मसल मेमोरी बनाता है। प्राइमरी एक्शन हमेशा “अगला कदम” दर्शाना चाहिए: नए के लिए Connect, आंशिक के लिए Continue setup, auth एक्सपायर होने पर Reconnect, और सब कुछ ठीक होने पर Manage। हर कार्ड पर दो बराबर जोर वाले बटनों से बचें — यह पेज को शोरगुल भरा बनाता है।

उदाहरण:

• अगर “Google” Connected है, तो प्राइमरी एक्शन Manage हो सकता है।
• अगर “Slack” कल रात फेल हुआ, तो Error दिखाएँ और प्राइमरी एक्शन Reconnect रखें।
• अगर “Stripe” आधा पूरा है, Needs setup दिखाएँ और Continue setup प्राथमिक रखें।

खाली अवस्थाएँ गाइड करें बिना एक मैनुअल फेंके:

• कोई इंटीग्रेशन इंस्टॉल नहीं: 2–3 पॉपुलर सुझाव दें और बताएं क्या अनलॉक होता है
• सर्च के लिए कोई परिणाम नहीं: सरल टिप दें जैसे “‘CRM’ या ‘billing’ आजमाएँ”
• पहली बार सेटअप: एक वाक्य में बताएं कि परमिशन क्या माँगी जाएगी और कौन सा डेटा एक्सेस होगा

इससे 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), टाइमस्टैम्प्स, और एक संक्षिप्त एरर संदेश जिसे यूज़र सपोर्ट टिकट में कॉपी कर सके।

चरण-दर-चरण: एक नया इंटीग्रेशन end to end जोड़ना

इंटीग्रेशन जोड़ना आसान होता है जब आप उसे एक छोटे प्रोडक्ट की तरह ट्रीट करते हैं। इसे एक लिस्टिंग चाहिए, कनेक्ट करने का तरीका, कनेक्शन स्टोर करने की जगह, और सफलता या विफलता के स्पष्ट परिणाम।

1) कैटलॉग एंट्री से शुरू करें

इंटीग्रेशन को अपने कैटलॉग में जोड़ें ताकि वह डायरेक्टरी में तब भी दिखाई दे जब तक किसी ने उसे कनेक्ट न किया हो। स्पष्ट नाम, छोटा विवरण, आइकन, और एक या दो कैटेगरी (Messaging, Payments) शामिल करें। सादे शब्दों में सेटअप अपेक्षाएँ लिखें, जैसे “एक अकाउंट कनेक्ट करें” और “एक वर्कस्पेस चुनें।” यह वह जगह भी है जहाँ आप बाद में आवश्यकता बताएँगे (OAuth scopes, required fields, supported features)।

2) कनेक्शन मेथड बनाएं

प्रोवाइडर के अनुरूप सबसे सरल कनेक्शन चुनें:

1. OAuth जब यूज़र को साइन इन करके एक्सेस अप्रूव करना हो (आम: Google, Slack)
2. API key जब यूज़र प्रोवाइडर से टोकन पेस्ट कर सके
3. Webhooks जब प्रोवाइडर इवेंट्स को आपके ऐप में पुश करे

3) क्रेडेंशियल सेव करें और एक Connection रिकॉर्ड बनाएं

जब यूज़र फ्लो पूरा करता है, तो उनके वर्कस्पेस/अकाउंट से जुड़ा एक Connection रिकॉर्ड बनाएं, सिर्फ यूज़र से नहीं। क्रेडेंशियल्स सुरक्षित रखें (रेस्ट पर एन्क्रिप्ट करें और पूर्ण सीक्रेट फिर न दिखाएँ)। सपोर्ट के लिए आवश्यक बेसिक्स सेव करें: प्रोवाइडर अकाउंट ID, बनाया कब, किसने कनेक्ट किया, और किन परमिशन्स की इजाज़त दी गई।

4) पहले-बार चेक चलाएँ और स्टेटस + प्रोग्रेस सेट करें

तुरंत एक साधारण टेस्ट चलाएँ (Stripe के लिए: अकाउंट डिटेल्स फेच करें)। अगर पास हुआ तो Connected दिखाएँ और प्रोग्रेस तैयार मार्क करें। अगर आंशिक रूप से पास हुआ (कनेक्ट तो हुआ पर परमिशन गायब), तो Needs attention मार्क करें और सटीक फ़िक्स पॉइंट करें।

5) असफल होने पर उपयोगकर्ता को क्या दिखेगा, तय करें

एक स्पष्ट संदेश, एक सिफारिश की हुई कार्रवाई, और एक सुरक्षित फॉलबैक दिखाएँ। उदाहरण: “We couldn’t reach Stripe. Check the API key or try again.” एक इंटीग्रेशन टूटने पर भी डायरेक्टरी उपयोग करने योग्य रखें।

अगर आप Koder.ai (koder.ai) पर बना रहे हैं, तो आप Planning Mode में पहले कैटलॉग, सेटअप फ्लो, और स्टेटस नियम ड्राफ्ट कर सकते हैं, फिर उस प्लान से UI और बैकएंड जनरेट कर सकते हैं।

त्रुटियाँ, retries, और सपोर्ट-फ्रेंडली हिस्ट्री

इंटीग्रेशन अक्सर नीरस कारणों से फेल होते हैं। अगर डायरेक्टरी उन कारणों को साफ़ तौर पर नहीं बता पाती, तो यूज़र आपकी ऐप को दोष देते हैं और सपोर्ट के पास काम करने के लिए कुछ नहीं रहता।

फेल्यर्स को उन बकेट्स में ग्रुप करें जिनसे असली फिक्स्स जुड़ी हों: लॉगिन एक्सपायर, मिसिंग परमिशन, प्रोवाइडर आउटेज, या रेट लिमिट। आंतरिक एरर कोड्स डिटेल्ड रखें, पर यूज़र को एक छोटा और समझने योग्य लेबल दिखाएं।

जब कुछ टूटता है, संदेश तीन चीज़ों का जवाब दे: क्या हुआ, यूज़र को क्या करना चाहिए, और आपकी सिस्टम अगले में क्या करेगी। उदाहरण: “Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.” यह एक कच्चे API एरर से ज़्यादा शांत और actionable है।

ऐसे retry नियम जो यूज़र्स को परेशान न करें

ऑटो-रिट्राई सिर्फ़ उन मामलों में करें जिन्हें यूज़र स्वयं ठीक नहीं कर सकता। एक साधारण नियम सेट काफ़ी होता है:

• प्रोवाइडर डाउन या नेटवर्क त्रुटि: बैकऑफ के साथ ऑटो-रिट्राई, आख़िरी सफलता समय रखें
• रेट लिमिट: पॉज़ करें, बाद में रीट्राई करें, और “Paused (rate limit)” दिखाएँ
• ऑथ एक्सपायर: रीट्राई रोकें और यूज़र से reconnect कहें
• मिसिंग परमिशन: रीट्राई रोकें और बताएँ कौन सी परमिशन चाहिए
• खराब कॉन्फ़िग: रोकें और उस सेटिंग की ओर इशारा करें जिसे भरना है

स्टेटस तब पुराना दिखने लगते हैं जब आप उन्हें रिफ्रेश न करें। एक हल्का हेल्थ चेक जॉब जोड़ें जो समय-समय पर टोकन की वैधता, आख़िरी सिंक का रन होना, और डायरेक्टरी बैज का मिलान चेक करे।

सपोर्ट के लिए उपयोगी हिस्ट्री

प्रति इंस्टॉल एक छोटा इवेंट हिस्ट्री रखें। आपको पूरा लॉग नहीं चाहिए — बस पर्याप्त breadcrumbs: टाइमस्टैम्प, इवेंट (“token refreshed”, “sync failed”), छोटा कारण, और किसने ट्रिगर किया (यूज़र या सिस्टम)। एक internal-only notes फ़ील्ड रखें ताकि सपोर्ट यह रिकॉर्ड कर सके कि उन्होंने क्या बदला और क्यों।

सर्च, फ़िल्टर्स, और डायरेक्टरी को व्यवस्थित करना

डायरेक्टरी एक बार कुछ ऐप्स पार कर जाए तो जल्दी गड़बड़ हो जाती है। लक्ष्य सरल है: लोगों को सेकंडों में वो मिल जाए जो उन्हें चाहिए, और समस्याएँ बिना हर कार्ड खोले ही दिख जाएँ।

इंटीग्रेशन नाम और कैटेगरी पर बेसिक सर्च से शुरू करें। ज़्यादातर यूज़र वही टाइप करते हैं जो उन्हें पहले से पता होता है (“Slack”, “Stripe”), इसलिए नाम मैचिंग fancy रैंकिंग से ज़्यादा मायने रखती है। कैटेगरी सर्च तब काम आती है जब उन्हें सिर्फ काम पता हो (payments, messaging)।

फ़िल्टर्स को वास्तविक इरादे के अनुरूप रखें। ये तीन अक्सर अधिकांश उपयोग केस कवर करते हैं:

• Connected (अब काम कर रहा है)
• Needs attention (त्रुटियाँ, एक्सपायर टोकन, मिसिंग परमिशन)
• Not set up (उपलब्ध पर कोई इंस्टॉल नहीं)

लिस्ट व्यवस्थित करने के लिए एक प्राथमिक ग्रुपिंग चुनें और उसी पर टिके रहें। उच्च संख्या पर category grouping अच्छा काम करता है (CRM, Payments, Messaging)। लोकप्रियता भी उपयोगी हो सकती है, पर तभी जब वह आपके यूज़र बेस को दर्शाए न कि मार्केटिंग को। एक व्यावहारिक डिफ़ॉल्ट: सबसे ज़्यादा उपयोग वाले पहले दिखाएँ, फिर बाकी को कैटेगरी से ग्रुप करें।

यह भी तय करें कि “हर कोई सब कुछ न देखे” का साफ़ प्लान क्या होगा। अगर कोई इंटीग्रेशन फीचर फ्लैग या प्लान टियर के पीछे है, तो या तो उसे अधिकांश यूज़र्स के लिए छिपाएँ या उसे डिसेबल्ड दिखाएँ एक छोटा कारण के साथ जैसे “Business plan.” ग्रे कार्ड्स से भरा पेज दिखाना टाला जाना चाहिए — यह स्क्रीन को टूटी हुई महसूस कराता है।

प्रदर्शन तेज़ रखने के लिए लिस्ट और डिटेल को अलग लोड करें। सूची को paginate या virtualize करें ताकि आप 30 भारी कार्ड एक साथ render न करें, और डिटेल तब लोड करें जब यूज़र किसी इंटीग्रेशन को खोले। डायरेक्टरी सारांश फ़ील्ड्स दिखा सकती है (Slack: Connected, Google: Needs attention, Stripe: Not set up) जबकि डिटेल पेज पूरा कनेक्शन हिस्ट्री फ़ेच करे।

उदाहरण: Slack, Google, और Stripe एक वास्तविक ऐप में

एक टीम वर्कस्पेस ऐप का कल्पना करें जिसका नाम 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.” डिटेल व्यू बचे हुए स्टेप को स्पष्ट करता है:

• Connect Stripe account (done)
• Choose billing plan mapping (done)
• Add webhook endpoint (not done)

यह “लगा हुआ है कि कनेक्टेड है पर कुछ काम नहीं कर रहा” की पीड़ा टालता है।

सामान्य गलतियाँ जो इंटीग्रेशन को मैनेज करना मुश्किल बनाती हैं

इंटीग्रेशन डायरेक्टरी आमतौर पर तब टूटती है जब एक ऐप कुछ इंटीग्रेशन से दर्जनों तक बढ़ता है। समस्याएँ शायद बड़ी तकनीकी नहीं होतीं — वे छोटे लेबलिंग और मॉडलिंग की गलतियाँ होती हैं जो रोज़ लोगों को भ्रमित करती हैं।

एक आम समस्या “installed” और “connected” को मिलाना है। Installed आम तौर पर मतलब है “आपके वर्कस्पेस में उपलब्ध।” Connected मतलब असल क्रेडेंशियल मौजूद हैं और डेटा बह सकता है। जब ये दो मिल जाते हैं, तो यूज़र एक ऐसा इंटीग्रेशन क्लिक करता है जो तैयार दिखता है और एक डेड एंड आता है।

एक और गलती बहुत सारे स्टेटस स्टेट्स बनाना है। टीमें एक साधारण बैज से शुरू कर देती हैं, फिर एज केस जोड़ती जाती हैं: pending, verifying, partial, paused, degraded, blocked, expiring, और भी बहुत कुछ। समय के साथ वे लेबल वास्तविकता से अलग हो जाते हैं क्योंकि कोई उन्हें सुसंगत नहीं रखता। एक छोटा सेट रखें जो आप वाकई चेक कर सकें, जैसे Not connected, Connected, Needs attention।

छुपी परमिशन्स भी परेशानी खड़ी करती हैं। कोई अकाउंट कनेक्ट कर देता है, फिर बाद में पता चलता है कि इंटीग्रेशन ने अपेक्षा से ज़्यादा एक्सेस मांगा। अंतिम “Connect” स्टेप से पहले स्कोप को स्पष्ट दिखाएँ, और डिटेल पेज पर भी दिखाएँ ताकि एडमिन ऑडिट कर सकें।

एक इंटीग्रेशन पर केवल एक कनेक्शन मानने का अनुमान न लगाएँ

कई ऐप्स को कई कनेक्शंस चाहिए: दो Slack वर्कस्पेस, कई Stripe अकाउंट्स, या साझा Google अकाउंट के साथ पर्सनल अकाउंट। अगर आप “एक इंटीग्रेशन = एक कनेक्शन” हार्डकोड कर देंगे तो बाद में बदसूरत वर्कअराउंड बनेंगे।

योजना बनाएं:

• एक इंटीग्रेशन के तहत कई कनेक्शंस होना
• एक स्पष्ट “डिफ़ॉल्ट” कनेक्शन (यदि चाहिए)
• साझा बनाम व्यक्तिगत कनेक्शंस
• यह देखने की जगह कि किसने कनेक्ट किया

लिस्ट व्यू हल्का रखें। जब आप इसे लॉग्स, फ़ील्ड मैपिंग्स, और लंबे विवरणों से भर देते हैं, तो स्कैनिंग धीमी हो जाती है। सूची में नाम, छोटा उद्देश्य, और सेटअप प्रोग्रेस रखें। इतिहास और उन्नत सेटिंग्स डिटेल पेज पर रखें।

त्वरित चेकलिस्ट और अगले कदम

एक स्केलेबल इंटीग्रेशन डायरेक्टरी एक सरल मॉडल और ईमानदार UI पर आती है। अगर यूज़र तीन सवालों के जल्दी जवाब पा सकें तो सिस्टम भविष्यवाणीयोग्य लगता है: क्या कनेक्टेड है, क्या टूटा है, और अगला क्या करना है?

शिप करने से पहले चेकलिस्ट:

• मॉडल अलग करें: Integration (कैटलॉग) vs Install (इस वर्कस्पेस में सक्षम) vs Connection (OAuth टोकन, API key, या webhook). अगर ज़रूरत हो तो Event जोड़ें केवल ऑडिट और सपोर्ट हिस्ट्री के लिए।
• स्टेटस व्युत्पन्न करें: लेबल्स की गणना चेक्स (टोकन वैध, scopes OK, webhook reachable) और सेटअप स्टेप्स पूर्ण होने से करें, ताकि बैज सटीक रहें।
• लिस्ट व्यू स्कैन करने योग्य रखें: हर रो में नाम, स्पष्ट स्टेटस लेबल, और एक “नेक्स्ट एक्शन” (Connect, Continue, Reconnect, Fix permissions) दिखे।
• लाइफसाइकल एक्शन्स को प्राथमिकता दें: Connect, Continue setup, Reconnect, Disable, और Disconnect आसानी से मिलें, छोटे कन्फर्मेशन्स के साथ।
• अनुमतियाँ दृश्य और ऑडिटेबल रखें: दिखाएँ कौन कनेक्ट या डिस्कनेक्ट कर सकता है, और रिकॉर्ड रखें कि किसने क्या बदला और कब।

अगला कदम: तीन इंटीग्रेशंस चुनें जिन्हें आप अच्छी तरह जानते हैं और उन्हें end-to-end मॉडल करें: एक चैट टूल (OAuth), एक Google-शैली अकाउंट कनेक्शन (OAuth with scopes), और एक पेमेंट टूल (API key + वेबहुक्स)। अगर आपका मॉडल बिना स्पेशल केसेस के इन तीनों को व्यक्त कर सके, तो यह आम तौर पर 30 तक स्केल कर जाएगा।