كيفية تكوين تكامل Salesforce

[lindsey (Lindsey Fogle)]

يغطي هذا الدليل خطوات التكوين المطلوبة لربط Discourse بـ Salesforce باستخدام إضافة Discourse Salesforce.

إضافة Discourse Salesforce متاحة ضمن خطة Enterprise.

مستوى المستخدم المطلوب: مسؤول (Administrator)

الخطوة 0: العثور على الأشخاص المناسبين في مؤسستك

قبل إجراء أي تغييرات في Discourse، تأكد أولاً من أنك تعرف الأشخاص المناسبين في مؤسستك الذين يجب إشراكهم للتعامل مع المتطلبات على جانب Salesforce.

مسؤول Salesforce

من هو: في معظم المؤسسات، يكون هذا الشخص هو من يطلق عليه فريقكم عادةً “مسؤول Salesforce” — أي الشخص الذي يدير تكوين منظمة Salesforce، وليس بالضرورة مسؤول أنظمة تكنولوجيا المعلومات.

ماذا يفعل: يتولى الإعداد الأولي على جانب Salesforce من خلال إنشاء تطبيق العميل الخارجي (External Client App) أو التطبيق المتصل (Connected App) في إعدادات Salesforce، وتكوين إعدادات OAuth، والحصول على مفتاح المستهلك (Consumer Key) وسر المستهلك (Consumer Secret).
ما يحتاجه: الوصول إلى Setup في Salesforce وتحديداً إلى External Client App Manager. يتطلب هذا في Salesforce صلاحية نظام Customize Application. تكون هذه الصلاحية مضمنة في ملف تعريف System Administrator القياسي. إذا لم يكن الشخص الذي يقوم بالإعداد يمتلك ملف تعريف System Administrator، فسيحتاج مسؤول Salesforce إلى منحه مجموعة صلاحيات تتضمن “Customize Application”.

مستخدم تكامل Salesforce

من هو: مستخدم Salesforce تُستخدم بيانات اعتماد حسابه بواسطة إضافة Discourse لإجراء مكالمات واجهة برمجة التطبيقات (API) إلى Salesforce.

ماذا يفعل: يوفر اسم المستخدم الذي يجب إدخاله في إعداد salesforce username في إعدادات Discourse Salesforce لتسهيل جميع مكالمات API من Discourse إلى Salesforce.

ما يحتاجه: يجب أن يمتلك هذا المستخدم:

الصلاحية	السبب في الحاجة إليها
API Enabled	مطلوبة لأي وصول لواجهة برمجة التطبيقات (API) في Salesforce
Create, Read, Edit on Lead	إنشاء وربط عملاء محتملين (Leads) من مستخدمي Discourse
Create, Read, Edit on Contact	إنشاء وربط جهات اتصال (Contacts) من مستخدمي Discourse
Create, Read, Edit on Case	إنشاء حالات (Cases) من موضوعات Discourse
Create on Case Comment	مزامنة ردود الموضوعات كتعليقات على الحالة (Case Comments)
Create on FeedItem (Chatter)	نشر نشاط الموضوع على Chatter

ملاحظة: يمكن أن يكون مستخدم تكامل Salesforce هو نفسه مسؤول Salesforce. ومع ذلك، وكأفضل ممارسة أمنية، نوصي باستخدام حساب منفصل بصلاحيات أقل وأكثر تحديداً لمستخدم التكامل.

الخطوة 1: إنشاء شهادة ومفتاح خاص

الدور: مسؤول Discourse

تستخدم Discourse Salesforce تدفق JWT Bearer للمصادقة مع Salesforce. يتطلب هذا زوج مفاتيح RSA: شهادة عامة يستخدمها Salesforce للتحقق من هوية الإضافة ومفتاح خاص يستخدمه Discourse لتوقيع طلباته.

1. اتبع هذه التعليمات لإنشاء زوج المفاتيح:
   • server.crt - شهادة عامة تثبت أن Discourse هو التطبيق المعتمد
   • server.key - مفتاح خاص يوقع طلبات واجهة برمجة التطبيقات (API) الخاصة بـ Discourse إلى Salesforce
2. أرسل ملف server.crt إلى مسؤول Salesforce الخاص بك حتى يتمكن من رفعه في الخطوة 3.
3. احتفظ بملف server.key للصقه في إعدادات Discourse Salesforce في الخطوة 5.

الخطوة 2: إنشاء تطبيق العميل الخارجي في Salesforce

الدور: مسؤول Salesforce

1. سجّل الدخول إلى Salesforce.

2. انقر على أيقونة الترس () في الزاوية العلوية اليمنى وحدد Setup.

   

3. في مربع البحث السريع (Quick Find box)، ابحث عن External Client App Manager وحدده.

   

4. انقر على New External Client App.

   

ملاحظة: تستخدم هذه الخطوات External Client App Manager، الذي تم تقديمه في إصدار Salesforce Spring '25. إذا كانت مؤسستك تعمل بإصدار أقدم، فقد تظهر واجهة المستخدم App Manager أو Connected Apps بدلاً من ذلك — الإعدادات الأساسية هي نفسها.

الخطوة 3: ملء المعلومات الأساسية وإعدادات OAuth

الدور: مسؤول Salesforce

1. املأ قسم Basic Information (حقلا اسم التطبيق والبريد الإلكتروني للتواصل مطلوبان).

   

2. قم بتوسيع قسم API (Enable OAuth Settings) وحدّد خيار Enable OAuth.

3. قم بتكوين الإعدادات التالية في هذا القسم:

   • Callback URL: أضف كلا الرابطين التاليين، مع استبدال <your-discourse-site> برابط موقع Discourse الكامل الخاص بك (مثال: meta.discourse.org):
     https://<your-discourse-site>
https://<your-discourse-site>/auth/salesforce/callback
     تأكد من عدم وجود شرطة مائلة (/) في نهاية أي من الرابط!
   • Available OAuth Scopes: أضف النطاقات الثلاثة التالية:
     • Access the identify URL service (id, profile, email, address, phone)
     • Manage user data via APIs (api)
     • Perform requests at any time (refresh_token, offline_access)
   • Flow Enablement: قم بتمكين كلا الخيارين التاليين:
     • Enable Client Credentials Flow
     • Enable JWT Bearer Flow — مطلوب حتى تتمكن الإضافة من إنشاء العملاء المحتملين (Leads) وجهات الاتصال (Contacts) والحالات (Cases)

4. تحت Certificate Upload، انقر على Upload files وارفع ملف server.crt من الخطوة 1.

   

5. انقر على Create.

الخطوة 4: استرداد مفتاح المستهلك وسر المستهلك

الدور: مسؤول Salesforce

1. على تطبيق العميل الخارجي الذي تم إنشاؤه حديثاً، انقر على علامة التبويب Settings.

2. قم بالتمرير لأسفل وقم بتوسيع إعدادات OAuth Settings.

3. انقر على Consumer Key and Secret.

   

4. أعد إدخال بيانات اعتماد تسجيل الدخول إلى Salesforce عند ظهور المطالبة.

5. انسخ Consumer Key و Consumer Secret وأرسلهما إلى مسؤول Discourse الخاص بك من أجل الخطوة 5.

الخطوة 5: تكوين إعدادات إضافة Discourse

الدور: مسؤول Discourse

1. في Discourse، انتقل إلى Admin → Plugins → Salesforce → Settings.

2. املأ الإعدادات التالية:

   الإعداد	القيمة
   salesforce enabled	ضع علامة في المربع لتمكين التكامل
   salesforce client id	مفتاح المستهلك (Consumer Key) من الخطوة 4
   salesforce client secret	سر المستهلك (Consumer Secret) من الخطوة 4
   salesforce rsa private key	الصق المحتوى الكامل لملف server.key من الخطوة 1
   salesforce username	اسم المستخدم لمستخدم تكامل Salesforce
   salesforce authorization server url	مطلوب فقط إذا كنت تستخدم نطاق Salesforce مخصصاً (مثال: https://mycompany.my.salesforce.com)

   

3. انقر على Save changes.

الخطوة 6: تفويض تطبيق Discourse في Salesforce

الدور: مستخدم تكامل Salesforce

1. انتقل إلى https://<your-discourse-site>/salesforce/admin/authorize، مع استبدال <your-discourse-site> برابط موقع Discourse الكامل الخاص بك (مثال: meta.discourse.org).
2. سيتم توجيهك إلى Salesforce وستُطلب منك تفويض التطبيق.
3. سجّل الدخول إلى Salesforce ومنح التطبيق الوصول.

بعد إكمال هذه الخطوة، يجب أن تكون جاهزاً. يمكنك التأكد من عملها بالانتقال إلى ملف تعريف أي مستخدم في Discourse — يجب أن يظهر خيار Sync with Salesforce في قائمة الإدارة.

استكشاف الأخطاء وإصلاحها

إذا لم تعمل الإضافة بعد الإعداد، فراجع هذه النقاط أولاً:

• فحوصات صحة لوحة الإدارة: تعرض الإضافة تنبيهين في /admin عندما تكون هناك تكوينات غير صحيحة:

  • SalesforceInvalidCredentials: مفتاح المستهلك أو سر المستهلك أو المفتاح الخاص RSA أو اسم المستخدم غير صحيح
  • SalesforceAppNotApproved: خطوة التفويض (الخطوة 6) لم تكتمل، أو تم رفض التطبيق المتصل

• تمكين التسجيل المفصل: قم بتشغيل إعداد الموقع salesforce_auth_verbose_logging لكتابة مخرجات مصادقة مفصلة في /logs الخاصة بـ Discourse. الأخطاء الشائعة وأسبابها:

العرض	السبب المرجح
“Insufficient privileges” عند إنشاء عميل محتمل (Lead) أو جهة اتصال (Contact)	لا يمتلك مستخدم التكامل أذونات الإنشاء/التحرير على كائنات Lead أو Contact
“Insufficient privileges” عند إنشاء حالة (Case)	يفتقر مستخدم التكامل إلى أذونات Case أو Case Comment
“Invalid grant” في خطوة التفويض	المفتاح الخاص RSA لا يتطابق مع الشهادة المرفوعة في الخطوة 3، أو لم يتم تمكين تدفق JWT Bearer
خطأ “DUPLICATE_VALUE” عند إنشاء Lead أو Contact	سلوك متوقع إذا كان المستخدم موجوداً بالفعل في Salesforce — تتعامل الإضافة مع هذا، ولكن راجع وثائق الإضافة الرئيسية للتفاصيل
منشورات Chatter لا تظهر	قد لا يمتلك مستخدم التكامل أذونات إنشاء FeedItem