Google Táblázatok
A B1 Export a B1.church hivatalos Google Táblázatok-kiegészítője. Bármely táblázathoz hozzáad egy oldalsávot, amellyel a B1 gyülekezetének adatai – személyek, adományok, csoportok vagy jelenlét – egy gombnyomással, igény szerint exportálhatók a megnevezett lapokra. A kiegészítő teljes egészében a felhasználó Google-fiókján belül fut; a minden exporthoz szükséges, csak olvasási API-hívásokon kívül nem kommunikál a ChurchApps szervereivel.
Mielőtt elkezdi
- Google-fiók, amellyel szerkesztési jogosultsága van abba a táblázatba, amelybe exportálni szeretne
- Egyházi adminisztrátor (vagy olyan személy, akinek van olvasási joga az exportálni kívánt adatokhoz), aki B1 API-kulcsot tud létrehozni
- A B1 Export kiegészítő telepítve a Google Workspace Marketplace-ről
Mit exportál
| Menüpont | Táblázatlap | Adatok |
|---|---|---|
| Export People | B1 People | ID, Display Name, First, Last, Email, Membership Status |
| Export Donations | B1 Donations | ID, Person ID, Date, Amount, Method, Batch ID |
| Export Groups | B1 Groups | ID, Name, Category, Member Count |
| Export Attendance | B1 Attendance | ID, Person ID, Visit Date, Service ID, Group ID |
Minden export lecseréli a megnevezett lap tartalmát – az exportálás újraindítása friss pillanatképet ad, nem pedig új sorokat fűz a meglévőkhöz. A táblázat többi lapja érintetlen marad.
Beállítás
1. B1 API-kulcs létrehozása a megfelelő hatókörökkel
- A B1Admin felületen lépjen a Beállítások → Fejlesztő → API-kulcsok menüpontra.
- Kattintson az Új API-kulcs gombra, nevezze el „Sheets Export”-nak, és adja meg azokhoz az adatokhoz a read (olvasási) hatóköröket, amelyeket exportálni szeretne:
people:reada személyek exportálásáhozdonations:readaz adományokhozgroups:reada csoportokhozattendance:reada jelenléthez
- Csak exportáláshoz használt kulcshoz nincs szükség
settings:writehatókörre – ez csak a webhookokat regisztráló összekötőknek (Zapier / Make) kell. Tartsa szűken ezt a kulcsot. - Mentse, és másolja ki a
cak_…kulcsot.
2. A kiegészítő telepítése
- Nyissa meg a táblázatot, amelybe exportálni szeretne.
- Bővítmények → Kiegészítők → Kiegészítők beszerzése.
- Keressen rá a B1 Export kiegészítőre, és telepítse. A Google kéri, hogy engedélyezze a táblázatokhoz való hozzáférést és a külső HTTP-kéréseket (hogy a kiegészítő hívhassa a B1 API-t).
A telepítés után a B1 Export menüpont megjelenik a Bővítmények menü alatt minden olyan táblázatban, amelyet ezzel a Google-fiókkal megnyit.
3. A kulcs csatlakoztatása
- Bővítmények → B1 Export → Csatlakozás… (vagy a B1 Export → Csatlakozás… a menüsoron, az első megnyitás után).
- Illessze be az API-kulcsot az oldalsávba, hagyja a Base URL mezőt
https://api.churchapps.orgértéken (kivéve, ha tesztkörnyezetben dolgozik), majd kattintson a Mentés gombra. - Kattintson a Kapcsolat tesztelése gombra – a zöld „Connection OK” üzenet jelzi, hogy a kulcs működik.
A kulcs a felhasználónkénti tulajdonságok (PropertiesService.getUserProperties()) között tárolódik – a Google-fiókjához kötődik, soha nem íródik a táblázatba, és a táblázat többi szerkesztője sem láthatja.
Exportálás futtatása
Az alábbi módok egyikével:
- A menüből – Bővítmények → B1 Export → Export People (vagy Export Donations / Export Groups / Export Attendance)
- Az oldalsávból – nyissa meg az oldalsávot (Csatlakozás…), és kattintson a megfelelő adathalmaz gombjára
Egy értesítés (toast) jelzi, amikor az exportálás kész – „N sor íródott ide: 'B1 People'.”
Jelentések építése az exportra
Az exportált lapok egyszerű Google Táblázatok-adatok. Saját elemzéseit úgy építheti fel, hogy hivatkozik ezekre a lapokra:
- Egy összesítő lap a
=SUMIF('B1 Donations'!E:E, "card", 'B1 Donations'!D:D)képlettel, amellyel összesítheti a kártyás adományokat - Egy szűrt nézet csak a tagokról:
=FILTER('B1 People'!A:F, 'B1 People'!F:F = "Member") - Egy diagram a jelenléti trendekről, amely a
B1 Attendancelapból dolgozik
Az exportálás újrafuttatása frissíti a mögöttes lapot; a képletei automatikusan frissülnek.
Ismétlődő exportok ütemezése
A kiegészítő alapértelmezés szerint igény szerint működik. Heti vagy havi exporthoz használja az Apps Script beépített, időalapú eseményindítóit:
- A táblázatban nyissa meg a Bővítmények → Apps Script menüpontot (ez a kiegészítő hozzá kötött szkriptjét nyitja meg).
- Kattintson a bal oldalsávban látható ⏰ Eseményindítók ikonra.
- Kattintson az Eseményindító hozzáadása gombra az
exportPeoplefüggvényhez (vagy bármely más exportfüggvényhez) – válassza az Időalapú típust, a Heti időzítőt, például Minden hétfőn reggel 6 órakor.
Az exportálás a háttérben fut a Google-fiókja alatt. Ha az API-kulcsot cserélik vagy visszavonják, az eseményindító e-mailben értesíti, a következő sikertelen futás után.
Engedélyek és adatvédelem
- A kiegészítő csak a
spreadsheets.currentonlyengedélyt kéri (csak azt a táblázatot érheti el, amelyben megnyitották), és ascript.external_requestengedélyt (hogy aUrlFetchApphívhassa a B1 API-t). Nem lát a Drive-ban, a Gmailben vagy más Google-adatokban. - A B1 API-kulcs felhasználónként tárolódik – a táblázat többi szerkesztője nem láthatja.
- Minden B1 API-hívás HTTPS-en keresztül,
Authorization: Bearer cak_…fejléccel történik.
Hibaelhárítás
- „No API key set” – nyissa meg a Bővítmények → B1 Export → Csatlakozás… menüpontot, és illessze be a kulcsot.
- „B1 rejected the API key (401)” – a kulcsot visszavonták, vagy hibás. Hozzon létre újat, és illessze be.
- „This API key lacks permission for /giving/donations (403)” – a kulcsnak nincs
donations:readhatóköre. Módosítsa a kulcs hatóköreit a B1Admin felületen. - A lap nem frissül a futtatás után – ellenőrizze, hogy a helyes lapnevet nézi (
B1 Peoplestb.). Az exportálás létrehozza a lapot, ha az még nem létezett. - „Quota exceeded” – az Apps Script felhasználónkénti napi kvótát szab a
UrlFetchApphívásokra (jellemzően több ezer hívás naponta). Nagy gyülekezetek sok rekorddal több napra oszthatják el az exportokat, vagy a nagy mennyiségű szinkronizációhoz használhatnak Make integrációt vagy egyedi megoldást.
Testreszabás
A kiegészítő nyílt forráskódú – az Apps Script projekt a B1Integrations/GoogleSheetsAddon/ tárolóban található. Ha olyan oszlopra van szüksége, amelyet nem exportálunk, egy további adathalmazra vagy más kimeneti formátumra, nyisson ott egy hibajegyet (issue) vagy egy pull requestet.
Lásd még
- Zapier – valós idejű szinkronizációhoz, nem igény szerinti exporthoz
- Make – összetettebb átalakításokkal járó szinkronizációhoz
- API-kulcsok (fejlesztői referencia)