Skip to main content
الاتصالات هي بيانات اعتماد يحتفظ بها المستخدم لخدمة خارجية (Linear وGitHub وSlack، …). يحدّد تطبيقك كيف يتم الحصول على تلك بيانات الاعتماد — موفّر اتصال — ويستخدمها وقت التشغيل لإجراء استدعاءات مُصادَقة إلى واجهة برمجة تطبيقات الطرف الثالث. حاليًا لا يُدعَم سوى OAuth 2.0. ستندمج الأنواع المستقبلية من بيانات الاعتماد (رموز الوصول الشخصية، مفاتيح API، المصادقة الأساسية) مع نفس الواجهة — التطبيقات التي تستخدم بالفعل defineConnectionProvider({ type: 'oauth', ... }) لن تحتاج إلى الترحيل.
يصف موفّر الاتصال عملية المصافحة الخاصة بـ OAuth التي يحتاجها تطبيقك. ينقر المستخدم على “إضافة اتصال” في إعدادات تطبيقك، ويُكمل شاشة موافقة المزوّد، ثم يتم إنشاء صف ConnectedAccount في مساحة عمله.يتطلّب الإعداد العملي ملفّين — موفّر الاتصال، وتصريح serverVariables مطابق في defineApplication يحتفظ ببيانات اعتماد عميل OAuth.
src/connection-providers/linear-connection.ts
src/application.config.ts
النقاط الرئيسية:
  • name هي سلسلة المعرّف الفريدة المستخدمة في listConnections({ providerName }) (بصيغة kebab-case، ويجب أن تطابق ^[a-z][a-z0-9-]*$).
  • displayName يظهر في علامة تبويب إعدادات كل تطبيق وفي قائمة أدوات الذكاء الاصطناعي.
  • clientIdVariable / clientSecretVariable هي أسماء، وليست قيماً — ويجب أن تطابق المفاتيح المصرَّح بها في defineApplication.serverVariables. يُدخِل مسؤول الخادم القيم الفعلية client_id وclient_secret عبر واجهة تسجيل التطبيق، ولا تُضمَّن أبدًا في مستودعك.
  • استخدم serverVariables (وليس applicationVariables) — بيانات اعتماد OAuth على مستوى الخادم، ويوجد تطبيق OAuth واحد لكل خادم Twenty.
  • إلى أن يتم ملء كلا serverVariables، تعرض علامة تبويب إعدادات كل تطبيق تلميح “بحاجة إلى مسؤول الخادم” ويكون زر “إضافة اتصال” معطّلًا.
  • type: 'oauth' هي القيمة الوحيدة المدعومة حاليًا. المميِّز متوافق مع الإصدارات المستقبلية: الأنواع المستقبلية ('pat'، 'api-key'، …) ستضيف كُتل تهيئة فرعية جديدة إلى جانب oauth.
عنوان URL لردّ النداء الخاص بـ OAuth الذي يحتاج موفّرك إلى إضافته إلى قائمة السماح هو:
بعض المزوّدين يسلّمونك بيانات وقت الاتصال تحتاج إلى الاحتفاظ بها قبل أن يصبح الاتصال قابلاً للاستخدام — المثال الكلاسيكي هو Slack، حيث يحدّد رد OAuth معرّف الفريق team_id الخاص بمساحة العمل الذي ستُربط به الأحداث الواردة. عيِّن onConnectLogicFunction للإشارة إلى دالة منطقية في التطبيق نفسه (حسب universalIdentifier الخاص بها)، وسيتم تشغيلها مباشرة بعد إنشاء ConnectedAccount.
src/connection-providers/slack-connection.ts
يعمل الـ hook بشكل غير متزامن في مساحة العمل التي تجري الاتصال (يتم وضعه في قائمة الانتظار، ولا يُنتظر انتهاؤه)، لذلك لن يؤدي hook بطيء أو فاشل إلى حظر أو تعطيل رد نداء OAuth — اجعله قابلاً للتكرار دون آثار جانبية (idempotent) ويتولى إعادة المحاولات بنفسه. يتلقى المعالج:
من هناك استخدم getConnection(connectedAccountId) لقراءة رمز الوصول الجديد واستدعاء واجهة برمجة تطبيقات المزوّد (على سبيل المثال، Slack auth.test) أو حفظ تعيين باستخدام مخزن المفاتيح والقيم.
داخل معالج دالة منطقية، تُرجِع listConnections({ providerName }) صفوف ConnectedAccount الخاصة بهذا التطبيق للمزوّد المحدَّد، مع رموز وصول محدَّثة.
src/logic-functions/handlers/create-linear-issue-handler.ts
يحتوي كل اتصال على:النقاط الرئيسية:
  • مرّر { providerName } للتصفية حسب المزوّد؛ واحذفه للحصول على كل الاتصالات التي يملكها هذا التطبيق عبر جميع المزوّدين.
  • يقوم الخادم بتحديث رمز الوصول بشفافية قبل الإرجاع. يرى معالجك دائمًا رمزًا صالحًا للاستخدام (أو سيكون authFailedAt مُعيّنًا).
  • getConnection(id) هي المعادِل لصف واحد.
عند نقر المستخدم “إضافة اتصال”، سيُطلب منه اختيار مستوى الرؤية:
  • لي فقط — بيانات الاعتماد خاصة بالمستخدم الذي قام بالاتصال. ستتمكّن أي دالة منطقية تُستدعى بالنيابة عنه (مشغّل مسار HTTP مع isAuthRequired: true) من رؤيتها؛ أمّا مشغّلات cron وأحداث قاعدة البيانات فلا.
  • مشتركة على مستوى مساحة العمل — يمكن لأي عضو في مساحة العمل استخدام بيانات الاعتماد. يمكن لمشغّلات cron/قاعدة البيانات رؤيتها أيضًا، لأنها لا تملك مستخدم طلب.
استخدم الخيار المناسب لكل معالج:
يُسمح بوجود اتصالات متعددة لكل (مستخدم، مزوّد)، لذا يمكن للمستخدم نفسه امتلاك “Linear شخصي” و”Linear للعمل” جنبًا إلى جنب.
بالنسبة لكل موفّر اتصال، يحتاج مسؤول الخادم أولًا إلى تسجيل تطبيق OAuth لدى الطرف الثالث.
  1. انتقل إلى إعدادات المطوّر لدى المزوّد (مثل https://linear.app/settings/api/applications/new).
  2. عيّن Redirect URI إلى \<SERVER_URL>/auth/apps/callback.
  3. انسخ Client ID وClient Secret المُنشأين.
  4. افتح التطبيق المُثبَّت في Twenty كمسؤول خادم → عيّن القيم على serverVariables المقابلة.
  5. بعد ذلك، يمكن لأعضاء مساحة العمل إضافة الاتصالات من قسم الاتصالات الخاص بكل تطبيق.