Zoho CRM konektor za Business Central
Zoho CRM konektor za Business Central
COMING / ABAK — Uputstvo za korisnike – opšte podešavanje i funkcionalnost
1. Svrha ekstenzije
Ova ekstenzija predstavlja opšti (generički) konektor koji Business Central-u omogućava da se autentifikuje prema Zoho CRM-u i poziva Zoho CRM REST API. Ekstenzija sama po sebi ne prenosi nikakve konkretne poslovne podatke (npr. prilike, kontakte ili firme) u Business Central – njena jedina svrha je da uspostavi i održava vezu sa Zoho-om (OAuth autentifikaciju) koju druge, dodatne ekstenzije mogu da koriste za konkretnu sinhronizaciju podataka.
Drugim rečima, ova ekstenzija je „temelj" integracije: jednom kada je podešena i veza je uspostavljena, na njoj se mogu graditi posebne, po meri prilagođene funkcionalnosti (npr. preuzimanje određenih Zoho podataka i njihovo upisivanje u Business Central) kroz odvojenu, korisnički specifičnu ekstenziju.
2. Preduslovi
Pre podešavanja ekstenzije potrebno je da već postoje sledeći podaci, pribavljeni od Zoho-a:
- Client ID – identifikator OAuth aplikacije kreirane u Zoho-u (Self Client).
- Client Secret – tajni ključ te OAuth aplikacije.
- Refresh Token – dobijen jednokratnom razmenom autorizacionog koda prilikom kreiranja Self Client-a u Zoho-u.
Napomena: Ovi podaci se pribavljaju jednom, prema posebnom uputstvu za Zoho OAuth podešavanje (Self Client), i ne zavise od Business Central-a.
3. Stranica podešavanja – „Zoho Integration Setup"
Sva podešavanja ove ekstenzije nalaze se na jednoj kartici – stranici Zoho Integration Setup. Do nje se dolazi preko pretrage (ikonica lupe u gornjem desnom uglu) unosom naziva „Zoho Integration Setup".
3.1 Grupa „Setup" (opšta podešavanja veze)
| Polje | Opis |
|---|---|
| Accounts Domain | Adresa Zoho servera za autentifikaciju (OAuth). Podrazumevana vrednost je https://accounts.zoho.eu za korisnike u Evropi. Menja se samo ako je Zoho nalog registrovan u drugom regionu (npr. .com, .in, .com.cn). |
| API Domain | Adresa Zoho CRM API servera prema kojem se šalju pozivi. Podrazumevana vrednost je https://www.zohoapis.eu. Mora odgovarati istom regionu kao i Accounts Domain. |
| Sync Interval Minutes | Opšte podešavanje intervala (u minutima) koje ova ekstenzija čuva radi kasnije upotrebe. Sama ova ekstenzija ne pokreće nikakvu automatsku sinhronizaciju – ovo polje ima smisla samo ako je iznad ove ekstenzije postavljena dodatna, korisnički specifična ekstenzija koja ga koristi. |
| Initial Backfill Days | Opšte podešavanje broja dana unazad koje ova ekstenzija čuva radi kasnije upotrebe, iz istog razloga kao i prethodno polje – koristi ga eventualna dodatna ekstenzija koja stvarno preuzima podatke. |
| Last Sync DateTime | Opšte polje za pamćenje vremena poslednje sinhronizacije, takođe namenjeno za upotrebu od strane dodatne ekstenzije koja stvarno prenosi podatke. Ova ekstenzija ga sama ne popunjava. |
3.2 Grupa „Zoho OAuth Credentials" (pristupni podaci)
U ovoj grupi se jednokratno unose pristupni podaci dobijeni od Zoho-a. Iz bezbednosnih razloga, ova polja se ne prikazuju nakon čuvanja (maskirana su i ne mogu se pročitati iz Business Central-a) – vrednosti se šifrovano čuvaju u Isolated Storage.
| Polje | Opis |
|---|---|
| Client ID | Client ID dobijen prilikom kreiranja Zoho OAuth aplikacije (Self Client). |
| Client Secret | Client Secret dobijen prilikom kreiranja Zoho OAuth aplikacije. |
| Refresh Token | Refresh Token dobijen jednokratnom razmenom autorizacionog koda (Self Client Generate Code postupak). Ovaj token se ne obnavlja ručno – Business Central ga koristi da automatski dobija nove pristupne tokene. |
Akcije na stranici
- Save Credentials – čuva unete vrednosti Client ID / Client Secret / Refresh Token. Nakon čuvanja, polja se prazne na ekranu (podaci ostaju sačuvani u pozadini, šifrovano).
- Test Connection – zatraži novi pristupni token od Zoho-a na osnovu sačuvanih podataka, kako bi se proverilo da li su kredencijali ispravni. Poruka „Connection successful" znači da je veza uspostavljena; u slučaju greške, potrebno je proveriti da li su Client ID, Client Secret i Refresh Token pravilno uneti i da Refresh Token nije opozvan na strani Zoho-a.
Napomena: Ove akcije treba pokrenuti samo jednom prilikom prvobitnog podešavanja, ili nakon promene Zoho OAuth aplikacije (npr. ako je token opozvan).
4. Kako funkcioniše autentifikacija u pozadini
Nakon što su kredencijali sačuvani, ekstenzija u pozadini vodi računa o pristupnim tokenima automatski, bez daljeg angažovanja korisnika:
- Kada je potreban pristup Zoho API-ju, ekstenzija prvo proverava da li već postoji važeći (nedospeo) pristupni token sačuvan iz ranije.
- Ako važeći token postoji, koristi se odmah, bez novog zahteva prema Zoho-u.
- Ako token ne postoji ili je istekao, ekstenzija automatski, u pozadini, zatraži novi pristupni token od Zoho-a koristeći sačuvani Refresh Token – korisnik ovo ne primećuje i ne mora ništa da preduzima.
- Novi pristupni token se ponovo bezbedno sačuva radi ponovne upotrebe do sledećeg isteka.
Ovaj mehanizam znači da se Refresh Token unosi samo jednom (ili nakon opoziva/promene), dok se sve naredno obnavljanje pristupa odvija automatski.
5. Šta ova ekstenzija ne radi sama po sebi
Važno je razumeti granicu ove ekstenzije: ona ne preuzima, ne prikazuje i ne upisuje nikakve konkretne Zoho podatke (npr. prilike, kontakte, firme) u Business Central. Ona samo:
- čuva podešavanja veze (adrese servera, pristupne podatke),
- obezbeđuje ispravan, važeći pristupni token kada je to potrebno,
- omogućava proveru da li veza sa Zoho-om radi (Test Connection).
Stvarno preuzimanje i obrada poslovnih podataka iz Zoho-a (npr. koji se Zoho podaci preuzimaju, u koje polje/tabelu u Business Central-u se upisuju, na koji interval se to radi) definisano je u posebnoj, korisnički specifičnoj ekstenziji koja se nadograđuje na ovu. Funkcionalnost te dodatne ekstenzije opisana je u zasebnom uputstvu.
6. Najčešći problemi i rešenja
Dugme „Test Connection" prijavljuje grešku
Najčešći uzrok je neispravan ili opozvan Refresh Token, ili neispravno unet Client ID / Client Secret. Rešenje: ponovo pribaviti Client ID, Client Secret i Refresh Token prema uputstvu za OAuth podešavanje, uneti ih preko dugmeta „Save Credentials", i ponovo probati „Test Connection".
Greška ukazuje na pogrešan region/domen
Proveriti da polja Accounts Domain i API Domain odgovaraju regionu u kojem je Zoho nalog registrovan (npr. .eu, .com, .in, .com.cn). Sva tri elementa – Zoho nalog, Accounts Domain i API Domain – moraju biti iz istog regiona.
Sačuvani kredencijali se ne vide na ekranu
Ovo je namerno ponašanje, ne greška: polja za Client ID / Client Secret / Refresh Token se iz bezbednosnih razloga nikada ne prikazuju nazad na ekranu nakon čuvanja. Ispravnost sačuvanih podataka se proverava preko dugmeta „Test Connection".
7. Kontakt
Za sva pitanja u vezi sa podešavanjem ove ekstenzije, ili za promenu Zoho OAuth pristupnih podataka, obratiti se timu zaduženom za Business Central podršku.