Salesforce
لا يوجد تطبيق Salesforce تثبّته لـ MailInApp، ولا تحتاج إلى واحد. تُجيب واجهة REST في Salesforce بـ JSON بسيط عبر HTTPS. ومصدر بيانات API في MailInApp، مع مصادقة OAuth2 JWT Bearer، يتعامل مباشرةً مع تدفق تسجيل الدخول من خادم إلى خادم في Salesforce: بلا شاشة موافقة، وبلا رمز تحديث تتابعه، ولا تصل كلمة مرور Salesforce إلى MailInApp أبدًا.
يُعِدّ هذا الدليل اتصالًا للقراءة فقط. يجلب صفوف Opportunity وAccount وContact والمنتجات إلى وسوم الدمج وكتل التكرار والمخططات المرتبطة بالبيانات، ويمكنه استيراد جهات اتصالك في Salesforce كجمهور. لا يكتب شيئًا في Salesforce.
كيف يعمل الاتصال
- يوقّع MailInApp تأكيد JWT قصير العمر بالمفتاح الخاص لتطبيقك.
- يرسل هذا التأكيد إلى نقطة إصدار الرموز في Salesforce، التي تتحقق من التوقيع بالشهادة التي رفعتها وتُرجع رمز وصول. لا يُرسَل أي اسم مستخدم أو كلمة مرور.
- يحفظ MailInApp رمز الوصول مؤقتًا ويستدعي به واجهة REST في Salesforce (استعلام SOQL). ويحصل على رمز جديد قبل انتهاء صلاحيته، أو إذا عاد استدعاء بخطأ عدم التفويض.
يحدث كل ذلك على الخادم، في كل عملية جلب. بعد الإعداد، لا شيء تحافظ عليه أو تعيد تفويضه.
إنشاء زوج مفاتيح
يحتاج تدفق JWT إلى زوج مفاتيح RSA: الشهادة لـ Salesforce، والمفتاح الخاص لـ MailInApp. إن لم يكن لديك زوج، فأنشئ زوجًا موقّعًا ذاتيًا باستخدام OpenSSL:
openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"
احفظ mailinapp.key في مكان آمن. تلصقه في MailInApp مرة واحدة، ثم يبقى مخفيًا.
إعداد Salesforce
تُنشئ Salesforce الآن عمليات التكامل الجديدة على شكل External Client Apps (إنشاء Connected Apps جديدة معطّل افتراضيًا في المؤسسات الحديثة).
- في Setup، افتح External Client App Manager وانقر New External Client App.
- أدخل الاسم (مثل MailInApp JWT) وبريدًا للتواصل، واترك Distribution State على Local.
- افتح API (Enable OAuth Settings) وحدّد Enable OAuth. لا يستخدم تدفق JWT حقل Callback URL أبدًا، لكنه إلزامي: يكفي
https://login.salesforce.com/services/oauth2/success. - في OAuth Scopes، أضف Manage user data via APIs (api) وPerform requests at any time (refresh_token, offline_access).
- في Flow Enablement، حدّد Enable JWT Bearer Flow وارفع الشهادة (
mailinapp.crt). انقر Create. - في تبويب Policies للتطبيق، انقر Edit. في OAuth Policies، اضبط Permitted Users على Admin approved users are pre-authorized، ثم اختر ملف التعريف أو مجموعة الأذونات للمستخدم الذي يسجّل MailInApp الدخول باسمه. هذا ما يجعل التدفق غير تفاعلي: من دونه تنتظر Salesforce أن يوافق شخص على شاشة الموافقة. احفظ.
- في تبويب Settings، افتح OAuth Settings وانقر Consumer Key and Secret. ترسل إليك Salesforce رمزًا بالبريد للتحقق من هويتك، ثم تعرض Consumer Key: هذا هو المُصدِر الذي يحتاجه MailInApp. لا تحتاج إلى السر.
يرى المستخدم الذي يسجّل MailInApp الدخول باسمه ما يراه هذا المستخدم في Salesforce فقط. الخيار الأنظف مستخدم تكامل مخصّص لديه صلاحية قراءة الكائنات التي تستخدمها رسائلك. الحقل المخفي عن هذا المستخدم (بأمان مستوى الحقل) لا يظهر في نتائج الاستعلام.
الاتصال في MailInApp
انتقل إلى مصادر البيانات ← + اتصال عبر API واملأ:
- رابط نقطة النهاية: رابط الاستعلام في مؤسستك مع استعلام SOQL، مثل
https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false. يمكنك كتابة الاستعلام بمسافات عادية، وسيتولى MailInApp ترميزه. - مسار البيانات:
records. تضع Salesforce الصفوف في مصفوفةrecordsبجانبtotalSizeوdone. - المصادقة: OAuth2 JWT Bearer، مع:
- رابط الرمز المميز:
https://login.salesforce.com/services/oauth2/token(أو رابط My Domain الخاص بكhttps://yourorg.my.salesforce.com/services/oauth2/token)؛ وhttps://test.salesforce.com/services/oauth2/tokenلبيئة sandbox. - المُصدِر: قيمة Consumer Key للتطبيق.
- الموضوع (Subject): اسم مستخدم Salesforce الذي يسجّل MailInApp الدخول باسمه.
- الجمهور (Audience):
https://login.salesforce.com(وhttps://test.salesforce.comلبيئة sandbox). - المفتاح الخاص: محتوى
mailinapp.key.
- رابط الرمز المميز:
انقر اختبار هذه الإعدادات: يحصل MailInApp على رمز حقيقي، ويشغّل الاستعلام، ويعرض الصفوف الأولى كما ستراها وسوم الدمج. بعد الحفظ، يتحقق اختبار الاتصال المحفوظ من الاتصال في أي وقت دون لصق المفتاح من جديد.
كل اتصال هو استعلام واحد. أنشئ اتصالًا لكل مهمة: الفرص المفتوحة لرسالة خط المبيعات، ودفتر الأسعار لكتالوج المنتجات، وجهات الاتصال للجمهور.
الاستعلام بـ SOQL
الاستعلام هو البيانات التي تحصل عليها بالضبط، فاختر الأعمدة التي تحتاجها رسالتك فقط.
- الحقول المرتبطة تعمل. تُرجع Salesforce حقل علاقة مثل
Account.Nameككائن متداخل، ويحوّله MailInApp إلى حقل اسمهAccount.Name. اكتبه{{alias.Account.Name}}في وسم دمج، أو{{Account.Name}}داخل كتلة تكرار. يعمل ذلك حتى ثلاثة مستويات (Account.Owner.Name)، وتُستبعد بياناتattributesالوصفية التي تضيفها Salesforce إلى كل سجل. - رتّب وحدّد العدد داخل الاستعلام. يحدد
ORDER BY CloseDateوLIMIT 10ترتيب الصفوف وعددها في كتلة التكرار. - حتى 1,000 صف في كل جلب، وهو ما يكفي لملخص أو كتالوج.
- تُجلب من جديد في كل عرض. كل إرسال، بما في ذلك كل تشغيل لإرسال متكرر، يعيد تشغيل الاستعلام، فتعرض الرسالة دائمًا بيانات Salesforce الحالية. وحده رمز OAuth يُحفظ مؤقتًا.
بعض الاستعلامات المفيدة:
SELECT Name, StageName, Amount, CloseDate, NextStep, Account.Name FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate
SELECT Name, ProductCode, UnitPrice, Product2.Description, Product2.DisplayUrl FROM PricebookEntry WHERE Pricebook2.IsStandard = true AND IsActive = true
SELECT Id, FirstName, LastName, Title, Email, HasOptedOutOfEmail, Account.Name, Account.Industry FROM Contact WHERE AccountId != null
استخدام البيانات
أضف الاتصال إلى رسالة من لوحة البيانات في الاستوديو، مع اسم مستعار (مثل pipeline) ودور:
- حقول الدمج: يُستخرج
{{pipeline.field}}من الصف الأول، وهو مناسب لرقم رئيسي واحد. - صفوف التكرار: تغذّي كتلة التكرار، التي تكرر محتواها لكل صف، مثل بطاقة لكل منتج.
- الصفوف نفسها تغذّي مخططات KPI والأعمدة والخطوط والدائرية: مؤشر KPI يجمع
Amountيصبح رقمًا مباشرًا لخط المبيعات المفتوح، ومخطط أعمدة مجمّع حسبStageNameيعرض خط المبيعات حسب المرحلة.
جزء مختلف لكل مستلم
يمكن لـ تصفية الصفوف في كتلة التكرار ولمرشّح المخطط مقارنة حقل من Salesforce ببيانات المستلم نفسه. مع قائمة جمهور فيها عمود company، تعرض القاعدة Account.Name يساوي {{company}} لكل بائع تجزئة فرصه الخاصة فقط، من استعلام واحد مشترك. تُنشأ نسخة كل مستلم من صفه الخاص لحظة الإرسال.
استيراد جهات اتصالك من Salesforce
جمهورك قائمة جهات اتصال في MailInApp. لملئها من Salesforce، أنشئ اتصال API باستعلام على Contact (الثالث أعلاه)، ثم انتقل إلى جهات الاتصال ← استيراد جهات الاتصال واختر اتصال عبر API.
يقرأ MailInApp الصفوف ببيانات الاعتماد المحفوظة، ويتعرّف على حقول Salesforce، ويقترح استخدام مطابقة Salesforce: FirstName ← first_name، وAccount.Name ← company، وId ← salesforce_id، وغيرها. جهة الاتصال التي فُعّل لها Email Opt Out (HasOptedOutOfEmail) في Salesforce تُميَّز في خطوة التحقق، التي تعرض استبعادها. ويُتعرَّف على تقرير Salesforce المُصدَّر بصيغة CSV بالطريقة نفسها. راجع استيراد العملاء المحتملين.
الاستيراد نسخة: شغّله مرة أخرى لإدخال جهات الاتصال الجديدة.
راجع رسائل تفاعلية مدعومة ببيانات Salesforce المباشرة لمثال كامل: ملخص أسبوعي لخط المبيعات مبني على هذا الاتصال.
