Salesforce

لا يملك MailInApp تطبيقًا لـ Salesforce تحتاج إلى تثبيته — ولا حاجة لك إلى واحد. فواجهة REST API الخاصة بـ Salesforce نفسها تجيب بـ JSON بسيط عبر HTTPS، ومصدر بيانات API في MailInApp مع مصادقة OAuth2 JWT Bearer مصمّم للتخاطب مباشرة مع مسار تسجيل الدخول من خادم إلى خادم في Salesforce: دون شاشة موافقة تفاعلية، ودون رمز تجديد يحتاج إلى متابعة، ودون أن تمسّ كلمة مرور Salesforce الخاصة بك MailInApp إطلاقًا.

يُعدّ هذا الدليل اتصالًا للقراءة فقط — يسحب صفوف Opportunity أو Account أو Contact إلى وسوم الدمج، وعناصر التكرار، وعناصر المخططات المربوطة ببيانات حيّة. ولا يكتب شيئًا في Salesforce.

آلية عمل الاتصال

1. يوقّع MailInApp تأكيد JWT قصير الأمد بالمفتاح الخاص لتطبيق Connected App في Salesforce.
2. يرسل ذلك التأكيد عبر POST إلى نقطة نهاية الرموز في Salesforce، التي تتحقق من التوقيع مقابل الشهادة التي رفعتها وتعيد رمز وصول — دون إرسال اسم مستخدم أو كلمة مرور أبدًا.
3. يخزّن MailInApp رمز الوصول مؤقتًا ويستدعي Salesforce REST API (باستعلام SOQL) مستخدمًا إياه رمزًا من نوع Bearer، مع تجديده تلقائيًا قبل انتهاء صلاحيته أو إن عاد أي استدعاء برفض لعدم التفويض.

تجري كل خطوة على الخادم، مع كل عملية جلب — فلا شيء يحتاج إلى إبقائه حيًّا أو إعادة تفويضه يدويًا بعد إعداده.

إعداد جهة Salesforce

1. في Salesforce Setup، انتقل إلى App Manager → New Connected App (أو New Connected App (Lightning)).
2. املأ حقول الاسم/البريد الإلكتروني الأساسية، ثم حدّد Enable OAuth Settings.
3. ضمن Use digital signatures، ارفع شهادة. وإن لم تكن لديك واحدة، فأنشئ شهادة موقّعة ذاتيًا ومفتاح RSA الخاص المطابق لها — فالشهادة تذهب إلى Salesforce، والمفتاح الخاص يذهب إلى MailInApp. احتفظ بالمفتاح الخاص في مكان آمن؛ فستلصقه في MailInApp مرة واحدة ويُقنَّع بعد ذلك.
4. أضف نطاق OAuth الذي يحتاجه تكاملك — ويكفي api (Manage user data via APIs) لقراءة السجلات.
5. احفظ، ثم عدّل سياسات Connected App: عيّن Permitted Users على Admin approved users are pre-authorized. وهذا ما يجعل المسار غير تفاعلي — فبدونه يتوقع Salesforce أن ينقر إنسان عبر شاشة موافقة، وهو ما لا يستطيعه تبادل JWT من خادم إلى خادم.
6. أسند مستخدم التكامل (مستخدم Salesforce حقيقي فُعّل له الوصول إلى API في ملفه الشخصي، أو مستخدم مخصّص للتكامل فقط) إلى Connected App عبر مجموعة صلاحيات (permission set).
7. دوّن Consumer Key الخاص بـ Connected App — وهو قيمة issuer التي يحتاجها MailInApp — ورابط My Domain لمؤسستك (Setup → My Domain)، مثل https://yourorg.my.salesforce.com.

الربط في MailInApp

من مصادر البيانات ← + اتصال API، عيّن ما يلي:

• نقطة النهاية — رابط استعلام REST لمؤسستك، مثل https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false (استعلام SOQL مرمَّز للرابط — راجع الاستعلام باستخدام SOQL أدناه).
• مسار البيانات — records. فاستجابة الاستعلام في Salesforce تغلّف الصفوف الفعلية في مصفوفة records إلى جانب الحقلين totalSize/done.
• المصادقة — OAuth2 JWT Bearer:
  • رابط الرموز — https://login.salesforce.com/services/oauth2/token لمؤسسات الإنتاج وDeveloper Edition، وhttps://test.salesforce.com/services/oauth2/token لبيئة sandbox.
  • المُصدِر (Issuer) — Consumer Key الخاص بـ Connected App.
  • الموضوع (Subject) — اسم مستخدم Salesforce لمستخدم التكامل (الهوية التي يؤكّدها JWT).
  • الجمهور المستهدف (Audience) — المضيف نفسه لرابط الرموز: https://login.salesforce.com (أو https://test.salesforce.com لبيئة sandbox).
  • المفتاح الخاص — مفتاح RSA الخاص المقترن بالشهادة التي رفعتها إلى Connected App.

انقر اختبار هذه الإعدادات لتأكيد الاتصال قبل الحفظ — فهو ينشئ رمزًا حقيقيًا ويعرض معاينة لأول بضعة صفوف. وبعد الحفظ، استخدم اختبار الاتصال المحفوظ في أي وقت لاحق لإعادة فحصه دون إعادة لصق المفتاح الخاص.

الاستعلام باستخدام SOQL

سلسلة الاستعلام في نقطة النهاية هي البيانات التي تعود إليك — فلا توجد واجهة منفصلة «لاختيار الحقول»، لذا صُغ استعلام SOQL ليعيد الأعمدة التي تحتاجها رسالتك بالضبط:

SELECT Name, Amount, StageName, CloseDate FROM Opportunity WHERE IsClosed = false

بعض الأمور الجديرة بالمعرفة عن شكل ما يعود:

• الحقول المسطّحة فقط. يعود حقل العلاقة مثل Owner.Email أو Account.Name كائن JSON متداخلًا ({"Owner": {"Email": "..."}})، ويُسقط محلّل الصفوف في MailInApp القيم المتداخلة بدلًا من تخمين طريقة تسطيحها. فإن احتجت إلى معرّف المالك أو الحساب وسمَ دمج قابلًا للاستخدام، فاختر حقلًا مسطّحًا بدلًا من ذلك — OwnerId مثلًا — بدلًا من مسار علاقة منقّط.
• حتى 1,000 صف في كل عملية جلب. وهذا وافر لرسالة ملخّص أو لوحة معلومات؛ وضيّق النطاق أكثر باستخدام WHERE/ORDER BY/LIMIT في الاستعلام نفسه إن أردت شريحة محددة فقط.
• يُجلب من جديد مع كل عرض. يعيد الإرسال المتكرر تشغيل الاستعلام ويعيد عرض العناصر المربوطة بالصفوف الحالية في Salesforce مع كل إرسال — ولا يوجد تخزين مؤقت سوى لرمز OAuth نفسه.

استخدام البيانات

بعد الربط، أضفه إلى مشروع من لوحة البيانات في الاستوديو باسم مستعار (مثل pipeline) ودور:

• حقول الدمج تحلّ {{pipeline.field}} من أول صف مُعاد — وهو مفيد لرقم رئيسي واحد.
• صفوف التكرار تغذّي عنصر تكرار — صف لكل Opportunity، يُعرض قائمةً أو جدولًا.
• ربط المجموعة هو ما ترتبط به عناصر بطاقة مؤشرات الأداء والمخطط الشريطي والخطي والدائري مباشرة — فتعيين حقل القيمة في بطاقة مؤشرات الأداء على Amount مع التجميع Sum يمنحك رقمًا حيًّا لـ«إجمالي خط المبيعات المفتوح» دون أي تجهيزات لوسوم الدمج، والمخطط الشريطي المجمّع حسب StageName يحوّل الاستعلام نفسه إلى تفصيل لخط المبيعات حسب المرحلة.

راجع بريد إلكتروني تفاعلي مدعوم ببيانات Salesforce الحيّة للاطلاع على مثال عملي كامل — ملخّص أسبوعي لخط المبيعات مبني بالكامل من هذا الاتصال.