Java-SDK für Zoho CRM-APIs bietet Wrapper für Zoho CRM-APIs. Deshalb ist der Aufruf einer Zoho CRM-API von Ihrer Java-Client-Anwendung nur ein Methodenabruf.

Laden Sie die SDK-Datei herunter, um mit Ihrem Projekt zu beginnen.

• SDK mit Abhängigkeiten
• SDK ohne Abhängigkeiten

Die Abhängigkeits-JARs sind:

• hamcrest-all-1.3
• httpclient-4.4.1
• httpcore-4.4.4
• httpmime-4.5.3
• json-20170516
• servlet-api-2.5
• commons-logging-1.1.3
• ZohoOAuthClient

Zoho-Client registrieren

Da die Zoho CRM-APIs mit OAuth2-Standards authentifiziert werden, sollten Sie Ihre Client-Anwendung mit Zoho registrieren. So registrieren Sie Ihre App:

1. Besuchen Sie diese Seite https://accounts.zoho.com/developerconsole.
2. Klicken Sie auf Client-ID hinzufügen.
3. Geben Sie den Client-Namen, die Client-Domäne und die Weiterleitungs-URL ein.
4. Wählen Sie den Client-Typ Webbasiert aus.
5. Klicken Sie auf Erstellen.
6. Ihre Client-App würde jetzt erstellt und angezeigt werden.
7. Die neu registrierten Elemente "Client-ID" und "Vertrauliche Client-Daten" der Anwendung können durch Klicken auf "Optionen" → "Bearbeiten" gefunden werden.
   (Optionen ist das Drei-Punkt-Symbol in der rechten Ecke).

Einrichtung

Java-SDK ist als JAR-Datei verfügbar. Das SDK erwartet Folgendes von der Client-App.

• Die Client-App sollte mindestens auf Java 7 laufen.
• Das JAR und die erforderlichen Konfigurationsdateien sollten nicht als SDK dem Client-Projekt hinzugefügt werden und beim Kompilieren und Ausführen im Klassenpfad verfügbar sein.
• Beim Starten der Anwendung muss die Methode ZCRMRestClient.initialize();, ohne Ausnahmen und erfolgreich, aufgerufen werden.

Konfigurationen

Ihre OAuth-Client-Details sollten dem SDK als Eigenschaftsdatei angegeben werden. Erstellen Sie eine Datei oauth_configuration.properties, legen Sie sie im Ordner Ressourcen ab und stellen Sie sicher, dass resources/oauth_configuration.properties in Ihrem Klassenpfad verfügbar ist.

Die Datei muss im nachfolgend gezeigten Format mit den folgenden Eigenschaften und den entsprechenden Werten vorhanden sein.

• client_id, client_secret und redirect_uri sind die Konfigurationen Ihres OAuth-Clients, die Sie nach dem Registrieren Ihres Zoho-Clients erhalten.
• Bereich kann einem oder mehreren (durch Komma getrennten) gültigen Zoho CRM-Bereichen entsprechen. Fügen Sie den Bereich Aaaserver.profile.Read Ihren angegebenen Bereichen hinzu. Dies ist obligatorisch.
• Access_type sollte auf offline oder online gesetzt werden.
• persistence_handler_class ist Ihre Implementierung der ZohoPersistenceHandler-Schnittstelle, die über Handler-Methoden zur Speicherung der OAuth-Daten verfügt. Beispiel: persistence_handler_class=com.zoho.oauth.clientapp.ZohoOAuthFilePersistence (oder) com.zoho.oauth.clientapp.ZohoOAuthDBPersistence (oder) Ihre eigene Persistenz-Handler-Klasse.
• Wenn Sie es vorziehen, unsere DB-Persistenz zu verwenden,müssen Sie die Schlüssel mysql_username und mysql_password für mysql-Konnektivität bereitstellen. Standardmäßig gilt mysql_username = "root" und mysql_password = "".

Anders als die oben genannten OAuth-Konfigurationen bietet das SDK auch Optionen, um bestimmte HTTP-Attributanforderungen zu überschreiben. Diese Konfigurationen sollten in einer Datei mit dem Namen zcrm_configuration.properties bereit gestellt werden, die sich ebenfalls im Ordner Ressourcen befinden sollte.

Im Folgenden finden Sie unterstützte Konfigurationen in der Datei zcrm_configuration.properties.

• Der Wert timeOut steht für die Anforderungszeitüberschreitung in Sekunden. Lassen Sie "timeOut" leer, wenn dieser Wert nicht benötigt wird.
• Der Wert userAgent enthält einen optionalen Namen für Ihre Client-Identifizierung.
• Der Wert minLogLevel steht für die minimale Protokollstufe für die Logger-Ausdrucke des SDK. Die unterstützten Werte lauten ALL, TRACE, DEBUG, INFO, WARNING, ERROR und OFF. Das standardmäßige Protokoll-Mindestniveau lautet WARNING.
• Wenn Sie mehrere Benutzer unterstützen, damit das SDK den anfordernden Benutzer erkennen kann, muss die E-Mail-Adresse des Anfordernden durch den folgenden Codeausschnitt definiert werden, bevor der eigentliche Methodenaufruf des SDK erfolgt.
  ZCRMRestClient.setCurrentUser(currentUserEmailId);
• Bei einem einzelnen Benutzer können Sie entweder die E-Mail-ID des Benutzers in ZCRMRestClient (siehe oben) für alle Anforderungen definieren oder die E-Mail-ID des Benutzers in der Datei zcrm_configuration.properties mit dem Schlüssel currentUserEmail als einmalige Konfiguration angeben.
• accessType (optional) – Art der Umgebung in CRM
  • Produktion – Umgebung mit aktiven, zahlenden Benutzern, die auf kritische Geschäftsdaten zugreifen.
  • Entwicklung – Umgebungen, in der Sie Erweiterungen, Integrationen und Entwicklungen vornehmen können, ohne Ihre Produktionsumgebungen zu beeinflussen.
  • Sandbox – Umgebungen, die speziell zum Testen der Anwendungsfunktionalität verwendet werden, bevor die Bereitstellung in der Produktion oder die Freigabe für Kunden erfolgt.
• domainSuffix (optional) – DC-Mehrfachunterstützung
  • us - www.zohoapis.com
  • eu - www.zohoapis.eu
  • cn - www.zohoapis.com.cn

OAuth-Persistenz

Nachdem die Anwendung vom Benutzer autorisiert wurde, können OAuth-Zugriffs- und Aktualisierungstoken für nachfolgende Benutzerdatenzugriffe auf Zoho CRM verwendet werden. Daher müssen sie von der Client-App beibehalten werden. 

Um dies zu ermöglichen, sollten Sie eine Implementierung der integrierten Schnittstelle ZohoPersistenceHandler schreiben, die die folgenden Rückrufmethoden enthält. 

• saveOAuthData(ZohoOAuthTokens-Token) – dies wird beim Abruf von Zugriffs- und Aktualisierungstoken von Zoho aufgerufen. 
• deleteOAuthTokens() – dies wird vor dem Speichern der neu erhaltenen Token aufgerufen. 
• getOAuthTokens() – dies wird vor dem Übermitteln einer Anforderung zum Abruf der gespeicherten Token aufgerufen. Diese Methode sollte das ZohoOAuthTokens-Objekt für die Bibliothek zur Verarbeitung zurückgeben. 

Der Name (zusammen mit seinem Paket) dieser Implementierungsklasse sollte als peristence_handler_class in oauth_configuration.properties angegeben werden. Zwei Beispielimplementierungen von ZohoPersistenceHandler sind leicht mit der Client-Bibliothek zugänglich. 

Sie könnten leicht eine der zwei Beispielimplementierungen verwenden (ZohoOAuthFilePersistence oder ZohoOAuthDBPersistence), die wir mit der Bibliothek zur Verfügung gestellt haben. 

ZohoOAuthDBPersistence verwendet eine individuelle MySQL-Persistenz. Um dies zu verwenden, müssen Sie Folgendes sicherstellen.  

• MySQL muss auf dem gleichen System mit Standard-Port 3306 ausgeführt werden. 
• Der Datenbankname muss zohooauth lauten. 
• Es muss eine Tabelle oauthtokens mit den Spalten useridentifier (varchar), accesstoken (varchar), refreshtoken (varchar) und expirytime (bigint) existieren.  

ZohoOAuthFilePersistence verwendet eine lokale Datei zum Schreiben und Lesen der OAuth-Token-Daten. Der vollständige Pfad der Datei, der von der Bibliothek für das Schreiben und Lesen der Token-Daten verwendet werden sollte, muss in der Datei oauth_configuration.properties als Wert der Eigenschaft oauth_token_file_path festgelegt werden. (Beispiel:  oauth_token_file_path=/user-Pfad/src/resources/oauthtokens.properties). 

Initialisierung

Nach dem Definieren der OAuth-Konfigurationsdatei und der OAuth-Persistenz-Handler-Klasse für Ihre App kann diese initialisiert werden.

Gewährungs-Token erzeugen

Für einen einzelnen Benutzer:

Die Entwicklerkonsole bietet eine Option zum Erzeugen eines Gewährungs-Tokens für einen Benutzer. Diese Option kann nützlich sein, wenn Ihre Anwendung nur einen Satz CRM-Benutzeranmeldedaten für alle Vorgänge oder zum Testen Ihrer Entwicklung verwendet.

1. Melden Sie sich am Benutzerkonto an.
2. Besuchen Siehttps://accounts.zoho.com/developerconsole.
3. Klicken Sie auf die Option Optionen → Eigener Client des Clients, für den die Autorisierung durchgeführt werden soll.
4. Geben Sie im Feld "Bereich" einen oder mehrere (durch Komma getrennte) gültige Zoho CRM-Bereiche an, die Sie autorisieren möchten. Wählen Sie dann die Ablaufzeit.
5. Kopieren Sie das angezeigte Gewährungs-Token.

Für mehrere Benutzer:

Bei mehreren Benutzern liegt es in der Verantwortung Ihrer Client-App, das Gewährungs-Token für Benutzer zu erzeugen, die einen Anmeldungsversuch unternehmen. Die Benutzerschnittstelle Ihrer Anwendung muss die Option Anmelden mit Zoho aufweisen, um die Gewährungs-Token-URL von Zoho zu öffnen, die die Zoho-Anmeldedaten des Benutzers abruft.

Nach erfolgreicher Anmeldung des Benutzers wird das Gewährungs-Token als Parameter an Ihre registrierte Weiterleitungs-URL gesendet.

Erzeugen von Zugriffs- und Aktualisierungs-Token

Nach dem Erhalt des Gewährungs-Tokens muss der folgende Codeausschnitt von Ihrer Hauptklasse ausgeführt werden, um Zugriffs- und Aktualisierungs-Token abzurufen. Bitte fügen Sie das kopierte Gewährungs-Token in den ausdrücklich genannten String ein.

Beachten Sie, dass der obige Codeausschnitt nur einmal pro Gewährungs-Token gültig ist. Nach der erfolgreichen Ausführung blieben die erzeugten Zugriffs- und Aktualisierungs-Token durch ihre Persistenz-Handler-Klasse erhalten.

Sobald die OAuth-Token gespeichert sind, verwenden die folgenden API-Aufrufe die persistierenden Zugriffs- und Aktualisierungs-Token. Das SDK sorgt für die Aktualisierung des Zugriffs-Tokens mithilfe des Aktualisierungs-Tokens, sofern und wenn erforderlich.

App starten

Das SDK erfordert den Aufruf der folgenden Codezeile bei jedem Starten der App.

Sobald das SDK durch die Zeile oben initialisiert wurde, könnten Sie jede API des SDK verwenden, um korrekte Ergebnisse zu erhalten.

Klassenhierarchie

Alle Zoho CRM-Entitäten werden als Klassen modelliert, die Mitglieder und Methoden für diese Entität aufweisen. ZCRMRestClient ist die Basisklasse des SDK. ZCRMRestClient weist Methoden zum Abrufen von Instanzen verschiedener anderer Zoho CRM-Entitäten auf.

Die Beziehungen zwischen den Klassen und die Klassenhierarchie des SDK folgen der Entitätenhierarchie innerhalb von Zoho CRM. Die Klassenhierarchie der verschiedenen Zoho CRM-Entitäten ist unten angegeben:

Jede Klassenentität verfügt über Funktionen zum Abrufen der eigenen Eigenschaften und zum Abrufen der Daten direkt untergeordneter Entitäten durch einen API-Aufruf.

Beispiel: Ein Zoho CRM-Modulobjekt (ZCRMModule) verfügt über Mitgliedsfunktionen zum Abrufen von Moduleigenschaften, wie Anzeigename, Modul-ID usw., sowie über Funktionen zum Abrufen aller untergeordneten Objekte (etwa ZCRMLayout).

Instanzobjekt

Es ist nicht immer effektiv, der gesamten Klassenhierarchie von oben nach unten zu folgen, um die Daten einer Entität auf einer unteren Ebene abzurufen, da dies zu API-Aufrufen auf jeder Ebene führen würde. Um dies zu vermeiden, verfügt jede Entitätenklasse über die Methode getInstance(), um ein eigenes Dummy-Objekt abzurufen. Außerdem sind Methoden zum Abrufen von Dummy-Objekten untergeordneter Entitäten vorhanden.

Wir weisen Sie darauf hin, dass getInstance()-Methoden nicht zum Ausfüllen dieser Eigenschaften führen, da kein API-Aufruf ausgelöst wird. Dies würde nur ein Dummy-Objekt zurückgeben, das nur für den Zugriff auf die nicht statischen Methoden einer Klasse verwendet wird.

Zusammenfassung:

• ZCRMRestClient.getModule("Contacts") würde das eigentliche Kontaktmodul zurückgeben, das über alle Eigenschaften des Kontaktmoduls verfügt, die über einen API-Aufruf eingetragen werden.
• ZCRMRestClient.getModuleInstance("Contacts") würde ein ZCRMModule-Dummy-Objekt zurückgeben, das sich auf das Kontaktmodul bezieht. Die Eigenschaften wären nicht ausgefüllt, da kein API-Aufruf erfolgt.

Um Datensätze aus einem Modul zu erhalten, müssen Sie nicht erneut mit ZCRMRestClient beginnen. Stattdessen können Sie eine Instanz von ZCRMModule mit ZCRMModule.getInstance() abrufen und dann die nicht statische Methode getRecords() der erstellten Instanz aufrufen. Dies würde den API-Aufruf vermeiden, der andernfalls ausgelöst worden wäre, um das Objekt ZCRMModule auszufüllen.

Zugriff auf Datensatzeigenschaften

Da Datensatzeigenschaften modulübergreifend dynamisch sind, wurden nur die allgemeinen Felder wie createdTime, createdBy, owner usw. als Standardmitglieder von ZCRMRecord festgelegt. Alle anderen Datensatzeigenschaften stehen als Übersicht im Objekt ZCRMRecord zur Verfügung.

Für den Zugriff auf die einzelnen Feldwerte eines Datensatzes verwenden Sie die verfügbaren Getter- und Setter-Methoden. Die Schlüssel der Übersicht zu den Datensatzeigenschaften sind die API-Namen der Modulfelder. API-Namen aller Felder für alle Module finden sich unter Setup → Marketplace → APIs → CRM-API → API-Namen.

• Zum Abrufen eines Feldwerts verwenden Sie record.getFieldValue(fieldAPIName);
• Verwenden Sie zum Festlegen eines Feldwerts record.setFieldValue(fieldAPIName, newValue);
  Stellen Sie beim Festlegen eines Feldwerts sicher, dass dieser Wert dem Datentyp des betreffenden Felds entspricht.

Handhabung von Antworten

APIResponse und BulkAPIResponse sind Wrapper-Objekte für Zoho CRM-API-Antworten. Alle API-Aufrufmethoden geben eines dieser beiden Objekte zurück.

• Eine nach Methoden suchende Entität gibt das APIResponse-Objekt zurück, während eine nach Methoden suchende Entitätenliste das BulkAPIResponse-Objekt zurückgibt.
• Verwenden Sie die Methode getData(), um nur die Entitätendaten aus dem Antwort-Wrapper-Objekt abzurufen. APIResponse.getData() würde ein einzelnes Zoho CRM-Entitätsobjekt zurückgeben, während BulkAPIResponse.getData() eine Liste von Zoho CRM-Entitätsobjekten zurückgeben würde.

Neben den Daten weisen diese Antwort-Wrapper-Objekte folgende Eigenschaften auf:

1. ResponseHeaders – Die verbleibende API ermittelt den aktuellen Tag/das Fenster und die verstrichene Zeit für das Zurücksetzen des aktuellen Fensters.
2. ResponseInfo – Alle anderen Informationen, sofern neben den eigentlichen Daten von der API bereitgestellt.
3. List<EntityResponse> – Status der einzelnen Entitäten in der Massen-API. Beispiel: Eine API zum Einfügen von Datensätzen kann aufgrund einiger Datensätze fehlschlagen. Dieses Array enthält den Erstellungsstatus der einzelnen Datensätze.

Ausnahmen

Unerwartetes Verhalten, darunter fehlerhafte API-Antworten und SDK-Anomalien, werden vom SDK gehandhabt und nur in Form einer einzigen Ausnahme ausgegeben: ZCRMException. Daher reicht es aus, nur diese Ausnahme im Client-App-Code abzufangen.