كيف تعمل مشاركة الملفات على السجلات (ContentDocumentLink)

إذا تساءلت يوماً لماذا يظهر ملف ما في المكان الذي يظهر فيه داخل Salesforce، أو اضطررت إلى الاستعلام عن الملفات في Apex أو في تقرير، فأنت بحاجة إلى نموذج البيانات الكامن خلف ذلك. تتكوّن Salesforce Files الحديثة من ثلاثة كائنات مترابطة، وحقلان على الرابط هما اللذان يقرران من يرى ماذا. هذا هو الدليل المرافق الموجّه للمسؤولين والمطوّرين بجانب مقالة من يستطيع رؤية ملف في Salesforce.

الكائنات الثلاثة

الكائن	ما هو	كم عددها
ContentDocument	الملف نفسه	واحد لكل ملف
ContentVersion	إصدار محدد من محتوى الملف	واحد لكل عملية رفع أو مراجعة
ContentDocumentLink	رابط يربط الملف بسجل أو مستخدم أو مجموعة	عدة روابط لكل ملف

عندما ترفع ملفاً فإنك تنشئ ContentVersion، يغلّفه Salesforce داخل ContentDocument. وعندما ترفق ذلك الملف بسجل أو تشاركه مع شخص ما، فإنك تنشئ ContentDocumentLink.

الملف هو ContentDocument. أما أين يقيم ومن يستطيع رؤيته فمكانه بالكامل في روابط ContentDocumentLink الخاصة به.

ContentDocumentLink: الحقل الأهم

يقول صف ContentDocumentLink إن “هذا الملف مرتبط بذلك الشيء، بمستوى الوصول هذا، ولهذا الجمهور.” وحقوله الرئيسية هي:

LinkedEntityId — ما يُرفق به الملف

معرّف الشيء الذي يرتبط به الملف:

• سجل (Account أو Opportunity أو Case أو كائن مخصص…) ← الملف “مرفق بـ” ذلك السجل.
• مستخدم أو مجموعة ← تتم مشاركة الملف مباشرة مع ذلك الشخص أو تلك المجموعة.

يمكن أن يحمل الملف الواحد عدة روابط في آنٍ واحد، بأن يكون مرفقاً بسجلين ومُشارَكاً مع مستخدم في الوقت نفسه. وكل رابط هو مسار مستقل لرؤية الملف.

ShareType — مستوى الوصول

القيمة	المستوى	ما يمكن فعله
V	Viewer	الفتح والتنزيل
C	Collaborator	العرض والتحرير ورفع إصدارات جديدة وتغيير المشاركة
I	Inferred	مستوى وصول موروث من الوصول إلى السجل المرتبط

القيمة Inferred (I) هي المهمة بالنسبة للملفات المرفقة بالسجلات: فوصول المستخدم إلى الملف مشتق من وصوله إلى السجل المرتبط به. وهذه هي الآلية الكامنة خلف عبارة “كل من يستطيع رؤية السجل يستطيع رؤية ملفاته”.

Visibility — أي جمهور

القيمة	الجمهور
AllUsers	المستخدمون الداخليون والخارجيون (مستخدمو المجتمع)
InternalUsers	المستخدمون الداخليون فقط
SharedUsers	المستخدمون الذين تتم مشاركة الملف معهم صراحةً فقط

هذا الحقل هو الذي يعطّل بهدوء الوصول عبر Experience Cloud: فالملف المرفق بسجل والذي قيمة Visibility فيه هي InternalUsers لن يظهر لمستخدمي المجتمع رغم قدرتهم على رؤية السجل. (مزيد عن ذلك في الملفات ومستخدمو الضيف / Experience Cloud.)

كيف يُحسم الوصول فعلياً

عند جمع كل ذلك، يستطيع المستخدم رؤية ملف ما إذا منحه إياه أيٌّ من روابط ContentDocumentLink الخاصة به:

1. رابط إلى سجل يمكنه الوصول إليه (ShareType بقيمة I) — وصول موروث من مشاركة السجل.
2. رابط مباشر إليه أو إلى مجموعته (ShareType بقيمة V/C).
3. عضوية في مكتبة، أو رابط عام (آليات منفصلة).

…ويجب أن يشمل Visibility الخاص بالرابط جمهوره. ومعظم تذاكر “الملف غير مرئي” تعود في الأصل إلى رابط مفقود أو إلى Visibility ضيق أكثر من اللازم.

الاستعلام عنه

ولأن كل ذلك مجرد بيانات، يمكنك فحصه مباشرة، مثل العثور على كل مكان تتم فيه مشاركة ملف:

SELECT ContentDocumentId, LinkedEntityId, ShareType, Visibility
FROM ContentDocumentLink
WHERE ContentDocumentId = '069...'

كل صف هو جمهور واحد يمكنه الوصول إلى الملف. ولتعداد الأشخاص، عليك بعد ذلك توسيع جمهور المشاركة الكامل لكل سجل في LinkedEntityId — وهنا يتضخم الأمر بسرعة.

من الصفوف إلى إجابة بلغة واضحة

الملف المرفق بعدة سجلات يرث كامل جمهور كل سجل — التسلسل الهرمي للأدوار وقواعد المشاركة والفرق وكل شيء — مضروباً عبر كل رابط ContentDocumentLink. وإعادة بناء ذلك يدوياً من الصفوف الخام هي بالضبط العمل الذي يخفي التعرّض غير المقصود. يتتبّع AgentForceAccess روابط ContentDocumentLink ومشاركة السجل الكامنة خلف كل منها، ويجيب عن سؤال “من يستطيع رؤية هذا الملف، ولماذا” بلغة واضحة.

الأسئلة الأكثر تكراراً

ما الفرق بين ContentDocument وContentVersion وContentDocumentLink؟

ContentDocument هو الملف نفسه (واحد لكل ملف). وContentVersion هو إصدار محدد من ذلك الملف (واحد لكل عملية رفع أو مراجعة). أما ContentDocumentLink فيربط ContentDocument بشيء آخر، سواء كان سجلاً أو مستخدماً أو مجموعة، ويحمل مستوى الوصول ومدى الظهور لهذا الرابط.

إلى ماذا يشير LinkedEntityId؟

هو معرّف الشيء الذي يرتبط به الملف. فبالنسبة لملف مرفق بسجل يكون معرّف السجل (Account أو Opportunity أو Case، إلخ)؛ وبالنسبة لملف تتم مشاركته مباشرة مع شخص أو مجموعة يكون معرّف User أو Group. ويمكن أن يحمل الملف الواحد عدة روابط ContentDocumentLink في آنٍ واحد.

ما هي قيم ShareType التي هي V وC وI؟

V = Viewer (الفتح والتنزيل)، وC = Collaborator (العرض والتحرير ورفع الإصدارات وتغيير المشاركة)، وI = Inferred (مستوى الوصول الذي يحصل عليه المستخدم بشكل غير مباشر من وصوله إلى السجل المرتبط). والقيمة Inferred هي الطريقة التي ينتقل بها الوصول إلى السجل ليصل إلى الملف.

ما الذي يفعله حقل Visibility؟

يحدد Visibility من يُكشف له الرابط: AllUsers (المستخدمون الداخليون والخارجيون/مستخدمو المجتمع)، أو InternalUsers (الداخليون فقط)، أو SharedUsers (المستخدمون الذين تتم مشاركة الملف معهم صراحةً فقط). وعادةً ما يحتاج مستخدمو المجتمع/Experience Cloud إلى AllUsers لرؤية ملف مرفق بسجل.