Le SDK Java pour API Zoho CRM fournit un wrapper pour les API Zoho CRM. Donc, invoquer une API Zoho CRM à partir de votre application Java cliente n'est qu'un appel de méthode.

Téléchargez le fichier SDK pour démarrer votre projet.

• SDK avec dépendances
• SDK sans dépendances

Les JAR de dépendance sont les suivants :

• 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

Enregistrement d'un client Zoho

Étant donné que les API Zoho CRM sont authentifiées par des normes OAuth2, vous devriez enregistrer votre application cliente auprès de Zoho. Pour enregistrer votre application :

1. Visitez cette page https://accounts.zoho.com/developerconsole.
2. Cliquez sur « Add Client ID » (Ajouter un ID client).
3. Entrez le nom du client, le domaine du client et l'URI de redirection.
4. Pour le type de client, sélectionnez Web based (Basé sur le Web).
5. Cliquez sur « Create » (Créer).
6. Votre application cliente devrait désormais être créée et s'afficher.
7. L'ID client et la clé secrète client de l'application nouvellement enregistrée sont accessibles en cliquant sur Options → Edit (Options → Modifier).
   (Les options sont représentées par l'icône des points de suspension dans le coin droit).

Configuration

Le SDK Java est disponible sous forme de fichier JAR. Le SDK attend les éléments suivants de l'application cliente.

• L'application cliente doit s'exécuter au minimum sous Java 7.
• Le fichier JAR et les fichiers de configuration requis doivent être ajoutés comme un SDK au projet client et ils doivent être disponibles dans le chemin d'accès aux classes au cours de la compilation et de l'exécution.
• Pendant le démarrage de votre application, la méthode ZCRMRestClient.initialize(); doit être appelée et invoquée avec succès sans aucune exception.

Configurations

Les détails de votre client OAuth doivent être fournis au SDK en tant que fichier de propriétés. Veuillez créer un fichier oauth_configuration.properties et le placer sous le dossier « resources », puis assurez-vous que « ressources/oauth_configuration.properties » est disponible dans votre chemin d'accès aux classes.

Le fichier doit avoir le format suivant avec les propriétés suivantes et leurs valeurs respectives.

• client_id, client_secret et redirect_uri sont les configurations du client OAuth que vous obtenez après avoir enregistré votre client Zoho.
• L'
• étendue peut correspondre à une ou plusieurs étendues Zoho CRM (séparées par des virgules) valides. Ajoutez l'étendue Aaaserver.profile.Read à vos étendues données. C'est obligatoire.
• access_type doit avoir la valeur offline (hors ligne) ou online (en ligne).
• persistence_handler_class correspond à votre mise en œuvre de l'interface ZohoPersistenceHandler, laquelle dispose de méthodes de traitement pour stocker les données OAuth. Exemple : persistence_handler_class=com.zoho.oauth.clientapp.ZohoOAuthFilePersistence (ou) com.zoho.oauth.clientapp.ZohoOAuthDBPersistence (ou) votre propre classe de traitement de persistance.
• Si vous préférez utiliser notre persistance de base de données, vous devez communiquer les clés mysql_username et mysql_password pour la connectivité mysql. Par défaut, il s'agit de mysql_username = "root" et mysql_password = "".

Outre les configurations OAuth ci-dessus, le SDK fournit également des options permettant de remplacer certains attributs de requête HTTP. Ces configurations doivent être fournies dans un fichier nommé zcrm_configuration.properties, lequel doit également être placé sous le dossier « resources ».

Voici les configurations prises en charge dans le fichier zcrm_configuration.properties.

• La valeur timeOut correspond au délai d'expiration de la demande exprimé en secondes. Si vous n'avez pas besoin de la valeur de délai d'expiration, laissez-la vide.
• La valeur userAgent fournit un nom facultatif pour identifier votre client.
• La valeur minLogLevel représente le niveau de journalisation minimum pour les impressions de journal du SDK. Les valeurs prises en charge sont ALL, TRACE, DEBUG, INFO, WARNING, ERROR et OFF. Le niveau de journalisation minimum par défaut est WARNING.
• Si vous servez plusieurs utilisateurs, pour que le SDK identifie l'utilisateur qui fait la demande, l'adresse e-mail du demandeur doit être définie grâce à l'extrait de code suivant avant de procéder à l'appel de méthode réel du SDK.
  ZCRMRestClient.setCurrentUser(currentUserEmailId);
• Autrement, s'il n'y a qu'un utilisateur, vous pouvez définir l'ID de messagerie de l'utilisateur dans ZCRMRestClient (comme ci-dessus) pour chaque demande ou indiquer l'ID de messagerie de l'utilisateur dans le fichier zcrm_configuration.properties avec la clé currentUserEmail en tant que configuration ponctuelle.
• accessType (facultatif) : type d'environnement dans CRM
  • Production : environnement dans lequel des utilisateurs payants actifs accèdent à des données professionnelles critiques.
  • Développement : environnements où vous pouvez étendre, intégrer et développer des solutions sans affecter vos environnements de production.
  • SandBox : environnements spécifiquement utilisés pour tester les fonctionnalités d'une application avant la phase de production ou sa publication pour les clients.
• domainSuffix (facultatif) - Support multi-DC.
  • us - www.zohoapis.com
  • eu - www.zohoapis.eu
  • cn - www.zohoapis.com.cn

Persistance OAuth

Une fois l'application autorisée par l'utilisateur, les jetons d'accès et d'actualisation OAuth peuvent être utilisés pour les demandes suivantes de données utilisateur à Zoho CRM. C'est pourquoi ils doivent être conservés par l'application cliente. 

Pour faciliter ce processus, vous devez écrire une mise en œuvre de l'interface ZohoPersistenceHandler intégrée qui possède les méthodes de rappel suivantes. 

• saveOAuthData(ZohoOAuthTokens tokens) : elle est invoquée lors de la récupération des jetons d'accès et d'actualisation auprès de Zoho. 
• deleteOAuthTokens() : cette méthode est invoquée avant d'enregistrer les jetons qui viennent d'être reçus. 
• getOAuthTokens() : cette méthode est invoquée avant de lancer une demande de récupération des jetons enregistrés. Cette méthode doit renvoyer l'objet ZohoOAuthTokens pour que la bibliothèque le traite. 

Le nom (avec son package) de cette classe de mise en œuvre doit être fourni en tant que peristence_handler_class dans oauth_configuration.properties. Deux exemples de mises en œuvre de ZohoPersistenceHandler sont disponibles dans la bibliothèque du client. 

Vous pouvez directement utiliser l'un des deux exemples de mises en œuvre fournis avec la bibliothèque, à savoir ZohoOAuthFilePersistence ou ZohoOAuthDBPersistence. 

ZohoOAuthDBPersistence utilise une persistance MySQL personnalisée. Pour cela, vous devez vous assurer des points suivants.  

• MySQL doit être en cours d'exécution sur la même machine servant au port par défaut 3306. 
• Le nom de la base de données doit être « zohooauth ». 
• Il doit y avoir un tableau « oauthtokens » comportant les colonnes « useridentifier » (varchar), « accesstoken » (varchar), « refreshtoken » (varchar) et « expirytime » (bigint).  

ZohoOAuthFilePersistence utilise un fichier local pour écrire et lire les données des jetons OAuth. Le chemin complet d'accès au fichier qui sera utilisé par la bibliothèque pour écrire et lire les données des jetons doit être spécifié dans le fichier oauth_configuration.properties en tant que valeur de la propriété « oauth_tokens_file_path ». (Par exemple,  oauth_tokens_file_path=/user-path/src/resources/oauthtokens.properties). 

Initialisation

L'application est prête à être initialisée après la définition du fichier de configuration OAuth et de la classe de traitement de la persistance OAuth pour votre application.

Générer des jetons d'autorisation

Pour un utilisateur unique :

La console développeur a une option pour générer directement un jeton d’autorisation pour un utilisateur. Cette option peut s'avérer pratique lorsque votre application doit utiliser les identifiants d'un seul utilisateur de CRM pour l'ensemble de ses opérations ou pour vos tests de développement.

1. Connectez-vous au compte de l'utilisateur.
2. Visitez https://accounts.zoho.com/developerconsole.
3. Cliquez sur l'option Options → Self Client (Client auto) pour le client auquel vous souhaitez donner une autorisation.
4. Entrez une ou plusieurs étendues (séparées par des virgules) Zoho CRM valides que vous souhaitez autoriser dans le champ Scope (Étendue) et choisissez l'heure d'expiration.
5. Copiez le jeton d'autorisation qui s'affiche sur l'écran.

Pour plusieurs utilisateurs :

Pour plusieurs utilisateurs, il incombe à votre application cliente de générer le jeton d'autorisation à partir des utilisateurs qui tentent de se connecter. L'interface utilisateur de votre application doit comporter une option « Login with Zoho » (Se connecter avec Zoho) pour ouvrir l'URL du jeton d'autorisation de Zoho, ce qui entraînera l'affichage d'une invite de saisie des identifiants de connexion Zoho de l'utilisateur.

Une fois l'utilisateur connecté avec succès, le jeton d'autorisation sera envoyé en tant que paramètre à votre URL de redirection enregistrée.

Générer des jetons d'accès et d'actualisation

Après l'obtention du jeton d'autorisation, l'extrait de code suivant doit être exécuté à partir de votre classe principale pour obtenir les jetons d'accès et d'actualisation. Veuillez coller le jeton d'autorisation copié dans le littéral de chaîne mentionné.

Veuillez noter que l'extrait de code ci-dessus n'est valable qu'une fois par jeton d'autorisation. Quand son exécution a réussi, les jetons d'accès et d'actualisation générés sont conservés dans votre classe de gestion de la persistance.

Quand les jetons OAuth ont été conservés, les appels d'API suivants utilisent les jetons d'accès et d'actualisation conservés. Le SDK va effectuer l'actualisation du jeton d'accès en utilisant le jeton d'actualisation, en fonction des exigences.

Démarrage de l'application

Le SDK requiert l'appel de la ligne de code suivante à chaque démarrage de votre application.

Une fois que le SDK aura été initialisé par la ligne ci-dessus, vous pourrez utiliser n'importe quelle API du SDK pour obtenir des résultats corrects.

Hiérarchie des classes

Toutes les entités Zoho CRM sont modélisées sous forme de classes comptant des membres et des méthodes applicables à chaque entité en particulier. ZCRMRestClient est la classe de base du SDK. ZCRMRestClient a des méthodes pour obtenir des instances de diverses autres entités Zoho CRM.

Les relations de classe et la hiérarchie du SDK suivent la hiérarchie des entités dans Zoho CRM. La hiérarchie des classes de diverses entités Zoho CRM est décrite ci-dessous :

Chaque entité de classe a des fonctions lui permettant de récupérer ses propres propriétés et les données de ses entités enfants immédiates grâce à un appel d'API.

Par exemple : un objet de module Zoho CRM (ZCRMModule) comportera des fonctions de membre permettant d'obtenir les propriétés d'un module (comme le nom de l'affichage, l'ID du module, etc.), ainsi que des fonctions pour récupérer tous ses objets enfants (comme ZCRMLayout).

Objet d'instance

Il n'est pas toujours efficace de respecter l'ensemble de la hiérarchie des classes à partir du niveau supérieur pour récupérer les données d'une entité de niveau inférieur, cela impliquant des appels d'API à tous les niveaux. Pour gérer ce problème, chaque classe d'entité dispose d'une méthode getInstance() pour obtenir son propre objet factice, ainsi que de méthodes pour obtenir les objets factices de ses entités enfant.

Veuillez noter qu'aucune propriété n'est indiquée pour les méthodes getInstance(), car cela ne renvoie pas d'appel d'API, mais seulement un objet factice à utiliser uniquement pour accéder aux méthodes non statiques de la classe.

En résumé,

• ZCRMRestClient.getModule("Contacts") renvoie le module Contacts réel, dont toutes les propriétés sont renseignées par le biais d'un appel d'API.
• ZCRMRestClient.getModuleInstance("Contacts") renvoie un objet factice ZCRMModule faisant référence au module Contacts, sans aucune propriété renseignée, étant donné que cela ne génère pas d'appel d'API.

Par conséquent, pour obtenir des enregistrements d'un module, vous n'avez pas besoin de commencer à partir de ZCRMRestClient. Au lieu de cela, vous pouvez obtenir une instance de ZCRMModule avec ZCRMModule.getInstance(), puis invoquer sa méthode getRecords() non statique à partir de l'instance créée. Cela permet d'éviter l'appel d'API qui aurait autrement été déclenché pour renseigner l'objet ZCRMModule.

Accès aux propriétés d'un enregistrement

Étant donné que les propriétés d'enregistrement sont dynamiques entre les modules, nous avons seulement donné les champs communs (createdTime, createdBy, owner, etc.) comme membres par défaut de l'objet ZCRMRecord. Toutes les autres propriétés d'enregistrement sont disponibles sous forme de carte dans l'objet ZCRMRecord.

Pour accéder aux valeurs des champs individuels d'un enregistrement, utilisez les méthodes get et set disponibles. Les clés de la carte des propriétés d'enregistrement sont les noms d'API des champs du module. Les noms d'API de tous les champs de tous les modules sont disponibles sous Setup → Marketplace → APIs → CRM API → API Names. (Configuration → Marketplace → API → API CRM → Noms d'API).

• Pour obtenir une valeur de champ, utilisez record.getFieldValue(fieldAPIName);
• Pour définir une valeur de champ, utilisez record.setFieldValue(fieldAPIName, newValue);
  Lorsque vous définissez une valeur de champ, veillez à ce que la valeur définie corresponde au type de données du champ pour lequel vous allez la définir.

Gestion des réponses

APIResponse et BulkAPIResponse sont des objets wrappers pour les réponses des API Zoho CRM. Toutes les méthodes d'appel d'API renverront l'un de ces deux objets.

• Une entité recherchant une méthode renvoie l'objet APIResponse, alors qu'une liste d'entités recherchant une méthode renvoie l'objet BulkAPIResponse.
• Utilisez la méthode getData() pour obtenir uniquement les données de l'entité à partir des wrappers de réponse. APIResponse.getData() renvoie un objet d'entité Zoho CRM unique, tandis que BulkAPIResponse.getData() renvoie une liste d'objets d'entité Zoho CRM.

À part les données, ces objets de wrapper de réponse ont les propriétés suivantes :

1. ResponseHeaders - nombre d'API restantes pour le jour/la fenêtre actuel(e) et temps écoulé pour la réinitialisation de la fenêtre actuelle.
2. ResponseInfo - toute autre information, si elle est fournie par l'API, en plus des données réelles.
3. List<EntityResponse> - statut des entités individuelles dans une API en bloc. Par exemple : une API d'insertion d'enregistrements peut partiellement échouer en raison de quelques enregistrements. Ce tableau donne le statut de création des enregistrements individuels.

Exceptions

Tous les comportements inattendus, comme des réponses d'API erronées ou des anomalies du SDK, sont gérés par le SDK et sont regroupés dans une exception unique, à savoir ZCRMException. Cela suffit donc pour identifier cette exception seule dans le code de l'application cliente.