Salesforce: إنشاء أو تحديث سجل

استخدم Salesforce: إنشاء أو تحديث سجل لعملية upsert (تحديث أو إدراج) لسجل Salesforce واحد من خطوة في Journey، تتم مطابقته بحقل معرف خارجي: يقوم بتحديث السجل عندما تكون القيمة موجودة بالفعل وينشئه عندما لا تكون كذلك. لا يمتلك Salesforce رمز API ثابت، لذا تتم المصادقة على هذه النقطة من خلال تطبيق متصل يتم تسجيله مرة واحدة للحساب بأكمله. لا يوجد حقل للرمز المميز في النقطة نفسها.

الاستخدامات النموذجية:

• إبقاء Salesforce متزامنًا: إنشاء أو تحديث Contact أو Lead أثناء تحرك المسافر عبر Journey، حتى يرى فريق المبيعات البيانات الحالية.
• مزامنة نشاط Journey في CRM: تعيين حقل عندما يصل المسافر إلى مرحلة هامة، حتى يتمكن فريق المبيعات من التصفية أو إعداد التقارير بناءً عليه.
• تجنب السجلات المكررة: المطابقة حسب المعرف الخارجي تعني أن المسافر الذي يمر عبر هذه النقطة مرة أخرى يقوم بتحديث نفس السجل بدلاً من إنشاء سجل جديد.

قبل أن تبدأ

أنشئ تطبيقًا متصلاً في مؤسسة Salesforce الخاصة بك وقم بتوصيله تحت الإعدادات > تكاملات الجهات الخارجية > Salesforce:

1. في Salesforce، أنشئ تطبيق عميل خارجي (External Client App) (أو تطبيقًا متصلاً كلاسيكيًا) مع تمكين OAuth ونطاق إدارة بيانات المستخدم عبر واجهات برمجة التطبيقات (api).
2. قم بتمكين تدفق بيانات اعتماد العميل (Client Credentials Flow) عليه واختر المستخدم الذي سيتم التشغيل باسمه. تكتب النقطة بصفتها ذلك المستخدم، لذا يقرر ملفه الشخصي الكائنات والحقول التي قد يلمسها.
3. في Pushwoosh، في مضيف نطاقي (My Domain host)، أدخل مضيف مؤسستك بدون https://، على سبيل المثال acme.my.salesforce.com.
4. في مفتاح المستهلك (Consumer Key) و سر المستهلك (Consumer Secret)، الصق بيانات اعتماد التطبيق. يتم تخزين السر للكتابة فقط: لن يعرضه Pushwoosh مرة أخرى، لذا الصق واحدًا جديدًا لاستبداله.
5. انقر على توصيل Salesforce.

بعد توصيل Salesforce، قم بتثبيت التكامل حتى تظهر النقطة في منشئ الرحلات.

هناك شيئان يجب أن يكونا في مكانهما أيضًا على جانب Salesforce:

• يجب أن يكون الحقل الذي تطابقه معلمًا بـ معرف خارجي (External ID) على ذلك الكائن. حقل نص عادي، حتى Email، ليس كافيًا — يرفض Salesforce الطلب بـ NOT_FOUND عندما لا يكون الحقل معرفًا خارجيًا.
• يحتاج مستخدم “التشغيل باسم” للتطبيق المتصل إلى وصول على مستوى الحقل إلى ذلك الحقل. الحقل الذي تم إنشاؤه من خلال الإعداد أو واجهة برمجة التطبيقات لا يمنح أي شيء بنفسه، وبدون الإذن يجيب Salesforce بنفس NOT_FOUND: Field name provided ... does not match an External ID — الحقل غير مرئي لذلك المستخدم، لذا من جانب واجهة برمجة التطبيقات فإنه غير موجود. أضفه إلى مجموعة أذونات مخصصة لمستخدم “التشغيل باسم”.

ملاحظة

الحقل المعلم بـ “معرف خارجي” و “فريد” هو الخيار المعتاد لمعرف الجهاز أو المستخدم، على سبيل المثال Pushwoosh_HWID__c مخصص على Contact.

تكوين النقطة

1. اسحب Salesforce: إنشاء أو تحديث سجل من قسم التكاملات في اللوحة اليسرى إلى اللوحة القماشية.
2. انقر نقرًا مزدوجًا على النقطة وأدخل اسم الخطوة.
3. في مضيف نطاقي (My Domain host)، أدخل نفس المضيف الذي يوجد عليه التطبيق المتصل.

4. في الكائن (Object)، أدخل اسم واجهة برمجة التطبيقات للكائن — Contact، Lead، أو كائن مخصص ينتهي بـ __c.

5. في حقل المعرف الخارجي (External id field)، أدخل اسم واجهة برمجة التطبيقات للحقل المعلم بـ “معرف خارجي”.

6. في قيمة المعرف الخارجي (External id value)، أدخل القيمة التي سيتم المطابقة عليها، وعادة ما تكون ماكرو مثل {{device:hwid}}.

7. في الحقول (Fields)، أضف صفًا واحدًا لكل حقل Salesforce لتعيينه. أدخل اسم واجهة برمجة التطبيقات للحقل والقيمة. يجب أن تكون الأسماء غير فارغة وفريدة. يجب أن تكون الحقول المطلوبة للكائن من بينها، وإلا يرفض Salesforce إنشاء سجل جديد. يمكن أن تكون القيمة نصًا ثابتًا أو ماكرو للمسافر مثل {{device:hwid}}، وهي نفس الماكروات الموجودة في نص Webhook. أو انقر على إدراج قيمة ديناميكية لاختيار سمة أنتجتها خطوة سابقة في هذه الرحلة، على سبيل المثال استجابة LLM أو قيمة Webhook معينة.

مثال

مع تعيين الكائن إلى Contact، و حقل المعرف الخارجي إلى Pushwoosh_HWID__c، و قيمة المعرف الخارجي إلى معرف جهاز المسافر ({{device:hwid}})، تقوم النقطة بمطابقة Contact موجود أو إنشاء واحد جديد. تعيين الحقول إلى Email مع بريد المسافر الإلكتروني ({{tag:Email}}) يملأ ذلك الحقل.

8. انقر على حفظ.

الاستجابة

يستمر المسافر إلى أي خطوة تقوم بتوصيلها بعد ذلك على اللوحة القماشية.

السمات بعد تشغيل الخطوة

السمة	ما تحتويه
salesforce_record_id	معرف السجل

كيفية استخدامها في الخطوات اللاحقة

لقد استمر المسافر بالفعل إلى الخطوة التالية بغض النظر عن هذه السمة. احفظها في Tag باستخدام تحديث ملف تعريف المستخدم إذا كنت بحاجة إلى الإشارة إلى هذا السجل المحدد لاحقًا، على سبيل المثال من خلال واجهة برمجة التطبيقات الخاصة بـ Salesforce.

الإخفاقات والاستجابات غير المتوقعة

افتح سجل المكالمات (Calls log) في درج النقطة وتحقق من الاستجابة:

• 401 — بيانات اعتماد التطبيق المتصل خاطئة، أو لم يتم تمكين تدفق بيانات اعتماد العميل عليه.
• NOT_FOUND في النص — اسم الكائن، أو حقل المعرف الخارجي، لا يتطابق مع أي شيء في تلك المؤسسة. تحقق من أن الحقل معلم بالفعل كمعرف خارجي.
• REQUIRED_FIELD_MISSING في النص — يتطلب إنشاء سجل جديد حقلاً لا ترسله النقطة. أضفه في الحقول.
• INVALID_FIELD في النص — اسم في الحقول ليس اسم واجهة برمجة تطبيقات على ذلك الكائن. ينتهي اسم واجهة برمجة التطبيقات للحقل المخصص بـ __c.

تنبيه

ترسل النقطة عملية upsert الخاصة بها كطلب مركب، وتجيب المكالمة المركبة بـ 200 حتى لو لم يتم كتابة السجل: يوجد الحكم في النص، تحت compositeResponse[0].httpStatusCode ثم compositeResponse[0].body[0].success. لذلك، لا يوقف السجل المرفوض المسافر — بل ينتقل كما لو أن الكتابة نجحت، لذا تحقق من سجل المكالمات عندما لا تظهر السجلات.

يؤدي الطلب الفاشل إلى إسقاط المسافر من الرحلة. انظر الأخطاء والطلبات الفاشلة.

سيناريو مثال: توجيه طلب استشارة داخل التطبيق إلى المبيعات

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

1. أضف عنصر دخول قائم على المشغل (Trigger-based entry) وقم بتعيينه ليتم تشغيله عند حدث AdvisorCallRequested.
2. أضف Salesforce: إنشاء أو تحديث سجل مباشرة بعده. قم بتعيين الكائن إلى Contact، و حقل المعرف الخارجي إلى Pushwoosh_HWID__c، و قيمة المعرف الخارجي إلى {{device:hwid}}. في الحقول، قم بتعيين Email إلى {{tag:Email}}.
3. انقر على حفظ.

بمجرد تشغيل هذا، يصل كل طلب استشارة داخل التطبيق إلى Salesforce كجهة اتصال (Contact)، تتم مطابقته بواسطة الجهاز بحيث يقوم النقر المتكرر بتحديث نفس جهة الاتصال بدلاً من إنشاء نسخة مكررة.