تخطي إلى المحتوى الرئيسي

جداول Google

B1 Export هي الإضافة الرسمية لجداول Google الخاصة بموقع B1.church. تضيف شريطاً جانبياً إلى أي جدول بيانات يُصدّر بيانات الأشخاص أو التبرعات أو المجموعات أو الحضور من كنيستك في B1 إلى علامات تبويب مسماة، وذلك عند الطلب وبنقرة واحدة. تعمل الإضافة بالكامل داخل حساب Google الخاص بالمستخدم، ولا تتصل بخوادم ChurchApps إلا عبر طلبات واجهة برمجة التطبيقات للقراءة فقط التي تُجرى مع كل عملية تصدير.

قبل أن تبدأ

  • حساب Google لديه صلاحية تحرير على جدول البيانات الذي تريد التصدير إليه
  • مسؤول الكنيسة (أو شخص لديه صلاحية قراءة للبيانات التي تريد تصديرها) القادر على إنشاء مفتاح API لـ B1
  • إضافة B1 Export مثبّتة من Google Workspace Marketplace

ما الذي تصدّره​

عنصر القائمةعلامة التبويبالبيانات
Export PeopleB1 PeopleID, Display Name, First, Last, Email, Membership Status
Export DonationsB1 DonationsID, Person ID, Date, Amount, Method, Batch ID
Export GroupsB1 GroupsID, Name, Category, Member Count
Export AttendanceB1 AttendanceID, Person ID, Visit Date, Service ID, Group ID

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

الإعداد​

1. إنشاء مفتاح API لـ B1 بالنطاقات المناسبة​

  1. في B1Admin، انتقل إلى Settings → Developer → API Keys.
  2. انقر على New API Key، وسمِّه "Sheets Export"، ثم امنح صلاحيات read للبيانات التي تنوي تصديرها:
    • people:read لتصدير الأشخاص
    • donations:read للتبرعات
    • groups:read للمجموعات
    • attendance:read للحضور
  3. المفتاح الذي يُستخدم للتصدير فقط لا يحتاج إلى settings:write، فهذا النطاق مخصص فقط للموصلات التي تسجّل webhooks (Zapier / Make). احتفظ بهذا المفتاح بأضيق نطاق ممكن.
  4. احفظ المفتاح cak_… وانسخه.

2. تثبيت الإضافة​

  1. افتح جدول البيانات الذي تريد التصدير إليه.
  2. انتقل إلى Extensions → Add-ons → Get add-ons.
  3. ابحث عن B1 Export وثبّتها. ستطلب منك Google منح الإضافة صلاحية الوصول إلى جداولك وإلى طلبات HTTP الخارجية (حتى تتمكن الإضافة من استدعاء واجهة B1 API).

بعد التثبيت، تظهر قائمة B1 Export ضمن القائمة Extensions في كل جدول بيانات تفتحه بهذا الحساب في Google.

3. ربط المفتاح​

  1. انتقل إلى Extensions → B1 Export → Connect… (أو إلى B1 Export → Connect… من شريط القوائم بعد أول فتح).
  2. الصق مفتاح API في الشريط الجانبي، واترك Base URL كما هو https://api.churchapps.org (إلا إذا كنت تختبر على بيئة التجريب)، ثم انقر على Save.
  3. انقر على Test Connection. ستظهر رسالة خضراء "Connection OK" تؤكد أن المفتاح يعمل.

يُخزَّن المفتاح في خصائص المستخدم (PropertiesService.getUserProperties()). فهو مرتبط بحسابك في Google، ولا يُكتب أبداً في الجدول، ولا يراه أي محرر آخر لجدول البيانات.

تشغيل عملية تصدير​

يمكنك أن تفعل أحد الأمرين:

  • من القائمة: انتقل إلى Extensions → B1 Export → Export People (أو Donations / Groups / Attendance)
  • من الشريط الجانبي: افتح الشريط الجانبي (Connect…) وانقر على زر مجموعة البيانات المناسبة

تظهر رسالة منبثقة تؤكد الانتهاء، مثل: "N row(s) written to 'B1 People'."، أي "تمت كتابة N صف في 'B1 People'."

بناء التقارير عليها​

علامات التبويب المصدَّرة هي بيانات جداول Google عادية. يمكنك بناء تحليلاتك الخاصة بالإشارة إليها:

  • علامة تبويب ملخّص تستخدم الصيغة =SUMIF('B1 Donations'!E:E, "card", 'B1 Donations'!D:D) لجمع هدايا البطاقات
  • عرض مُرشَّح لأعضاء فقط باستخدام =FILTER('B1 People'!A:F, 'B1 People'!F:F = "Member")
  • مخطط يعرض اتجاهات الحضور انطلاقاً من B1 Attendance

عند إعادة تشغيل التصدير، يتم تحديث علامة التبويب الأساسية، وتتحدّث صيغك تلقائياً.

جدولة عمليات التصدير المتكررة​

الإضافة تعمل عند الطلب افتراضياً. للتصدير الأسبوعي أو الشهري، استخدم المشغّلات الزمنية المدمجة في Apps Script:

  1. انتقل إلى Extensions → Apps Script في جدول البيانات (يفتح هذا النص البرمجي المرتبط بالإضافة).
  2. انقر على أيقونة ⏰ Triggers في الشريط الجانبي الأيسر.
  3. انقر على Add Trigger للدالة exportPeople (أو أي دالة تصدير أخرى)، واختر Time-driven، ثم Week timer، مثلاً Every Monday 6am.

يعمل التصدير في الخلفية ضمن حساب Google الخاص بك. وإذا أُعيد تعيين مفتاح API أو أُلغي، فسيرسل لك المشغّل بريداً إلكترونياً في المرة التالية التي يفشل فيها.

الخصوصية والأذونات​

  • تطلب الإضافة صلاحية spreadsheets.currentonly (فلا يمكنها الوصول إلا إلى جدول البيانات المفتوح فيه) وصلاحية script.external_request (حتى يتمكن UrlFetchApp من استدعاء واجهة B1 API). ولا تطّلع على Drive أو Gmail أو أي بيانات أخرى من Google.
  • يُخزَّن مفتاح B1 API لكل مستخدم، ولا يمكن للمحررين الآخرين لجدول البيانات نفسه رؤيته.
  • تُجرى جميع استدعاءات B1 API عبر HTTPS مع الترويسة Authorization: Bearer cak_….

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

  • "No API key set": انتقل إلى Extensions → B1 Export → Connect… والصق المفتاح.
  • "B1 rejected the API key (401)": المفتاح أُلغي أو أنه غير صحيح. أنشئ مفتاحاً جديداً والصقه من جديد.
  • "This API key lacks permission for /giving/donations (403)": المفتاح لا يملك صلاحية donations:read. حدّث نطاقات المفتاح في B1Admin.
  • لا يتم تحديث الجدول بعد التشغيل: تأكد من أنك تنظر إلى علامة التبويب الصحيحة (مثل B1 People). تُنشئ عملية التصدير علامة التبويب إذا لم تكن موجودة.
  • "Quota exceeded": تفرض Apps Script حصصاً يومية لكل مستخدم على UrlFetchApp (عادةً آلاف الاستدعاءات يومياً). قد تحتاج الكنيسة الكبيرة التي تملك سجلات كثيرة إلى تقسيم عمليات التصدير على عدة أيام، أو استخدام Make أو تكامل مخصص للمزامنة عالية الحجم.

تخصيص الإضافة​

الإضافة مفتوحة المصدر، ويوجد مشروع Apps Script في مستودع B1Integrations/GoogleSheetsAddon/. إذا أردت عموداً غير مُصدَّر، أو مجموعة بيانات إضافية، أو صيغة إخراج مختلفة، فافتح issue أو PR في ذلك المستودع.

انظر أيضاً​