Guide de transition-Caseware Cloud API V1 à V2

L'API V1 a aidé de nombreux clients à automatiser les flux de travail et à s'assurer que les données dans Caseware Cloud sont à jour et exactes. Cependant, au fur et à mesure que les besoins des clients ont évolué, nous avons entendu des commentaires sur les limites de la V1, en particulier en ce qui concerne le travail avec les unités opérationnelles et les étiquettes. Sur la base de ce retour d'information, nous avons apporté des améliorations judicieuses à l'API V2 afin de mieux répondre à vos besoins et de vous aider à travailler plus efficacement.

Les principales améliorations de l'API V2 sont les suivantes

  • Compatibilité avec les unités opérationnelles (UO): Meilleure prise en charge de la gestion de plusieurs unités commerciales au sein de votre organisation.

  • API de gestion des étiquettes: Un nouvel ensemble de points de terminaison API pour automatiser la gestion et l'attribution de balises afin d'améliorer l'organisation et le filtrage.

  • Documentation SDK conviviale pour les développeurs: Documentation SDK claire et complète conçue pour simplifier l'intégration et le développement.

L'API V2 sera lancée en même temps que la V1 afin d'assurer une compatibilité ascendante, de sorte que vos intégrations existantes continueront à fonctionner pendant la transition. Cependant, l' API V1 sera obsolète le 30 octobre 2025, ce qui vous laisse amplement le temps de migrer vers la V2 sans interruption.

Nous avons conçu ces changements pour qu'ils aient le plus grand impact possible sur l'amélioration de votre expérience, en nous basant directement sur les commentaires que nous avons reçus. Ce guide vous guidera à travers les nouvelles fonctionnalités, répondra aux questions les plus courantes concernant les différents cas d'utilisation et les flux de travail, et vous aidera à assurer une transition en douceur et réussie vers l'API V2.

Foire aux questions (FAQ)

Informations générales sur l'API V2

Q1) Quelle est la différence entre API V1 et V2 ?

A1) L'API V2 apporte plusieurs améliorations majeures par rapport à la V1, notamment une meilleure prise en charge des unités opérationnelles (BU), un système de gestion des balises plus souple et un SDK convivial pour les développeurs, avec une documentation plus claire. Ces mises à jour sont conçues pour améliorer l'efficacité, réduire la courbe d'apprentissage pour les développeurs et introduire les meilleures pratiques d'intégration.

Q2) Comment l'API V2 améliore-t-elle la compatibilité avec les unités opérationnelles ?

A2) Dans la version 2 de l'API, nous sommes passés de l'utilisation d'identifiants spécifiques à un site à celle d'identifiants uniques globaux (GUID). Cela garantit que les données sont identifiables de manière unique dans toutes les unités opérationnelles (UO), ce qui facilite la gestion et l'extension des intégrations inter-unités sans conflits. Pour les organisations qui n'utilisent pas les BU, les GUID constituent toujours un moyen plus robuste et plus évolutif de traiter les données, en s'alignant sur les meilleures pratiques et en améliorant la flexibilité de l'intégration.

Q3) Mes intégrations V1 actuelles continueront-elles à fonctionner ?

A3) Oui, même avec le lancement de l'API V2, Caseware continue de supporter la V1 pour s'assurer que vos intégrations ne sont pas perturbées.

Q4) Existe-t-il un calendrier pour l'abandon de la V1 ?

A4) La V1 continuera d'être prise en charge parallèlement à la V2, vous pouvez donc continuer à utiliser vos intégrations actuelles pour l'instant. Cependant, l'API V1 sera obsolète le 30 octobre 2025. Nous vous recommandons de passer à la version 2 avant cette date afin d'assurer une expérience fluide et de profiter pleinement des nouvelles fonctionnalités et améliorations.

Q5) Où puis-je trouver la documentation relative aux nouvelles fonctionnalités de l'API V2 ?

A5) Une documentation détaillée sur l'API V2, y compris des informations sur les nouveaux points de terminaison et les nouvelles fonctionnalités, est disponible dans notre documentation SDK. Elle comprend des descriptions complètes des nouveaux points de terminaison V2, des exemples et des lignes directrices pour vous aider à passer de la V1 à la V2. La documentation du SDK est organisée de manière à prendre en charge les deux versions, de sorte que vous pouvez facilement basculer entre les points d'extrémité V1 et V2 en fonction de vos besoins d'intégration. En outre, les développeurs peuvent télécharger la spécification de l'API ouverte directement à partir de la documentation du SDK, ce qui fournit un format structuré pour l'intégration de la nouvelle API V2.

Sélection de la version de la spécification de l'API Caseware Cloud

Q6) Dois-je passer à la V2 même si je n'utilise pas de Business Units ou de Tags ?

A6. Oui, nous vous recommandons de passer à l'API V2, même si vous n'utilisez pas encore de Business Units ou de Tags. L'API V1 sera un jour obsolète et, dès lors, votre intégration existante ne sera plus prise en charge. En outre, du point de vue des meilleures pratiques, la V2 introduit des points de terminaison qui utilisent des identificateurs uniques globaux (GUID), qui offrent des solutions plus fiables et plus évolutives que les clés non uniques. Cette transition vous permettra d'assurer la pérennité de votre intégration.

Q7) Y a-t-il des limitations ou des problèmes connus avec la V2 ?

A7) Bien que l'API V2 offre plusieurs améliorations, il y a quelques limitations dont il faut être conscient. Par exemple, les points de terminaison des étiquettes utilisent encore des ID plutôt que des GUID, et nous prévoyons d'y remédier dans les prochaines versions. Nous prévoyons également d'apporter régulièrement des mises à jour mineures à la V2, en tenant compte des commentaires et en ajoutant de nouvelles fonctionnalités. Nous vous invitons également à nous faire part de vos commentaires afin de nous aider à prioriser les améliorations et à faire en sorte que la V2 réponde à vos besoins.

Q8) Des mises à jour de l'API V2 sont-elles prévues à l'avenir ?

A8) Oui, nous continuerons à publier régulièrement des mises à jour mineures pour l'API V2, en y incorporant de nouvelles fonctionnalités, des améliorations et des corrections de bogues. Nous recommandons aux développeurs de consulter régulièrement le site de documentation du SDK pour se tenir au courant des dernières modifications et télécharger les spécifications Open API les plus récentes. Veuillez noter que l'API V1 ne recevra plus de mises à jour à l'avenir. Nous vous encourageons donc à passer à la V2 pour bénéficier des améliorations et de l'assistance continues.

Questions sur le passage de V1 à V2

Q1) Comment planifier ma transition de V1 à V2 ?

A1) Vous pouvez passer de V1 à V2 de deux manières : une migration échelonnée ou une commutation complète.

  • Migration progressive : Migrez les différentes intégrations (par exemple, les entités, le personnel ou les groupes) dans des phases distinctes, en testant et en mettant en œuvre chacune d'entre elles au fur et à mesure.

  • Commutateur complet : Mettez à jour toutes les intégrations existantes en une seule fois, mais veillez à effectuer des tests approfondis dans un environnement d'essai avant de procéder au basculement complet.

Plan your transition

  1. Consultez la documentation de l'API V2.

  2. Choisissez votre approche de la migration (progressive ou complète).

  3. Mise à jour du code d'intégration pour effectuer des appels API vers les points d'extrémité V2.

  4. Contrôler l'intégration après la commutation.

Ce processus garantit une transition en douceur, quelle que soit votre approche.

Pour obtenir des conseils détaillés sur la migration de cas d'utilisation spécifiques tels que les entités, le personnel et autres, reportez-vous aux sections correspondantes ci-dessous.

Q2) Comment dois-je gérer les références d'identification si je dispose d'une base de données de correspondance ?

A2) Si vous utilisez une base de données de mappage ou un logiciel intermédiaire pour stocker et référencer les identifiants d'objets CW (tels que les identifiants d'entités), nous vous recommandons de mettre à jour votre base de données pour stocker à la fois l'identifiant CW et le CWGuid correspondant.

Avant de migrer vers la version 2, vous pouvez utiliser l'API V1 pour rechercher des données par ID CW. Dans la réponse, vous trouverez le CWGuid de chaque objet, que vous pourrez ensuite utiliser pour mettre à jour votre table de référence. Cela permettra à votre système d'être prêt pour la transition vers la V2, où les CWGuids seront l'identifiant principal.

Q3) Puis-je continuer à utiliser V1 tout en passant à V2 ?

A3) Oui, vous pouvez continuer à utiliser la V1 pendant que vous migrez vers la V2. Les intégrations V1 et V2 peuvent fonctionner en parallèle pendant ce processus de migration. Par exemple, vous pouvez exécuter votre intégration des entités sur V2 alors que votre intégration du personnel utilise toujours V1

Q4) Dois-je modifier le code de mes intégrations actuelles ?

A4) Oui, pour profiter des nouvelles fonctionnalités de la V2, vous devrez mettre à jour vos appels API vers les nouveaux points d'extrémité de la V2. Les spécificités des changements requis dépendront des points d'extrémité que vous utilisez actuellement dans la V1.

Q5) Comment puis-je obtenir de l'aide pendant la transition ?

A5) Notre équipe d'assistance est à votre disposition pour répondre à toutes les questions ou difficultés que vous rencontrerez au cours du processus de transition.

Q6) Dois-je créer de nouveaux clients API pour la V2 ?

A6) Non, vous n'avez pas besoin de créer de nouveaux clients API ou de nouvelles clés pour V2. Vos clients V1 existants continueront à fonctionner de manière transparente avec V2. Toutefois, si vous préférez, vous pouvez créer de nouveaux clients API spécifiquement pour V2. Une fois que vous êtes passé à la version 2, vous pouvez choisir de supprimer les anciens clients V1 afin de vous assurer que les intégrations V1 ne sont plus utilisées.

Questions relatives aux cas d'utilisation pour la migration V2

Entités

Q1. Création d'un IDEAScript

A1. For Business Units: Pour créer une entité dans une unité commerciale spécifique, utilisez le point de terminaison Créer une entité dans une unité commerciale. Indiquez le nom abrégé de l'unité commerciale dans les paramètres du chemin d'accès, ainsi que les autres informations requises dans le corps de la demande. L'API créera l'entité dans l'unité commerciale spécifiée. La réponse comprendra un CWGuid, qui devra être utilisé pour toute opération future sur l'entité, en remplacement de l'ancien identifiant de l'entité.

Visualisation du point de terminaison pour la création d'une entité dans une unité d'affaires

Si vous n'utilisez pas de Business Units, utilisez le point de terminaison standard Créer une entité , comme vous l'avez fait dans la V1. Cela créera l'entité dans votre site cloud, et ici aussi le CWGuid doit être utilisé pour les opérations ultérieures.

Visualisation du point de terminaison utilisé pour créer une entité lorsqu'il n'y a pas d'unités d'affaires.

Q2. Comment appeler les points de terminaison Get, Update et Delete Entity dans la V2 ?

A2. Dans l' API V2, vous devez utiliser les CWGuids au lieu des entityIds pour identifier les entités dans les points de terminaison Get, Updateet Delete . Voici comment cela fonctionne :

  1. Lors de la création d'une entité ou de la récupération d'une liste d'entités (par exemple, via le point de terminaison Search Filtered List), la réponse comprendra un CWGuid pour chaque entité.

  2. Pour les opérations suivantes (Get, Update, Delete), vous devez utiliser le CWGuid fourni dans la réponse pour référencer l'entité spécifique.

Pour les entreprises des unités commerciales (UC) , l'utilisation des CWGuids garantit que l'entité est identifiée de manière unique dans toutes les UC, ce qui simplifie les opérations dans les unités commerciales multiples. Le système utilisera le guide pour effectuer l'opération demandée (obtenir, mettre à jour ou supprimer) dans n'importe quelle unité opérationnelle, garantissant ainsi une intégration transparente.

Utilisateurs

Q3) How do I Create users in V2?

A3. La création d'utilisateurs dans la V2 est similaire à celle de la V1, avec une fonctionnalité supplémentaire pour les entreprises de l'unité d'affaires. Voici comment cela fonctionne :

Pour toutes les entreprises :

Créez des utilisateurs dans la V2 en utilisant le point de terminaison Créer un utilisateur , comme dans la V1. Le processus reste le même pour la plupart des paramètres.

Affichage du point d'accès utilisé pour créer un utilisateur.

Pour les entreprises de l'unité opérationnelle (UO) :

Les entreprises peuvent spécifier les noms abrégés des unités d'affaires afin d'accorder à l'utilisateur l'accès à des unités d'affaires spécifiques. Cela simplifie la gestion de l'accès des utilisateurs dans plusieurs unités commerciales. Voici un exemple de code avec la liste des BU :

Accorder aux utilisateurs l'accès à une liste d'unités d'affaires.

Réponse

Après la création de l'utilisateur, la réponse comprendra un CWGuid, qui devra être utilisé pour les opérations futures (Get, Update, Delete) à la place de l'ancien identifiant de l'utilisateur.

Q4) Comment obtenir les coordonnées d'un utilisateur ?

A4) Dans la V2, pour récupérer les détails d'un utilisateur, utilisez le point de terminaison Get User Details et fournissez le CWGuid de l'utilisateur dans les paramètres du chemin d'accès. Dans la version 1, vous auriez utilisé l'ID de l'utilisateur, mais dans la version 2, c'est le Guid qui est requis.

Q5) Comment obtenir la liste des unités opérationnelles auxquelles un utilisateur a accès ?

A5) Pour obtenir la liste des unités opérationnelles auxquelles un utilisateur a accès, utilisez le point de terminaison Get User Details et fournissez le CWGuid de l'utilisateur. La réponse comprendra toutes les unités opérationnelles auxquelles l'utilisateur a actuellement accès.

Q6) Comment affecter ou désaffecter un utilisateur du personnel à différentes unités opérationnelles ?

A6) Vous pouvez affecter ou désaffecter un utilisateur d'une unité opérationnelle lors de la création ou de la mise à jour de l'utilisateur.

Créer un utilisateur

Fournir une liste de noms abrégés d'unités commerciales dans la demande, en précisant les unités commerciales auxquelles l'utilisateur doit avoir accès.

Mise à jour des données de l'utilisateur

Vous pouvez soit affecter l'utilisateur à de nouvelles unités d'affaires, soit le supprimer des unités existantes.

Pour affecter l'utilisateur à une BU :

Inclure toutes les unités opérationnelles auxquelles l'utilisateur devrait avoir accès, y compris celles auxquelles il a déjà accès.

Pour supprimer l'accès à une BU :

N'incluez que les UB auxquelles l'utilisateur doit conserver l'accès. Toute BU ne figurant pas dans la liste sera supprimée de l'accès de l'utilisateur.

Attribution de l'accès aux unités d'affaires.

Important :
Si vous n'incluez pas le champ Business Unit dans la demande de mise à jour, aucune modification ne sera apportée à l'accès BU de l'utilisateur.

Groupes

Q7) Comment créer un client ?

A7) Dans la V2, pour créer un groupe, il faut utiliser le point de terminaison Créer un groupe et fournir les paramètres nécessaires dans le corps de la demande. Contrairement à la V1, où vous auriez reçu un groupId, dans la V2, vous recevrez un CWGuid dans la réponse, qui devra être utilisé pour toute opération future sur ce groupe spécifique (comme Get, Update ou Delete).

Q8) Comment ajouter des utilisateurs à un groupe ?

A8) Pour ajouter un utilisateur à un groupe dans V2, utilisez le point de terminaison "Mise à jour de l'affectation d'un utilisateur à un groupe". Dans la V2, au lieu d'utiliser l'ID du groupe et les ID des utilisateurs comme dans la V1, vous devrez fournir le CWGuid du groupe et les CWGuids des utilisateurs que vous voulez ajouter dans la demande.

En ajoutant ou en supprimant des utilisateurs à des groupes et en affectant ces groupes à des unités commerciales spécifiques, vous pouvez gérer efficacement l'accès des utilisateurs aux différentes unités commerciales par le biais de leur appartenance à un groupe.

Visualisation du point de terminaison pour ajouter des utilisateurs à un groupe.

Q9) Comment obtenir la liste des unités opérationnelles auxquelles un groupe a accès ?

A9) Pour obtenir la liste des unités opérationnelles auxquelles un groupe a accès, utilisez le point de terminaison Obtenir les détails du groupe et fournissez le CWGuiddu groupe. La réponse comprendra toutes les unités opérationnelles auxquelles le groupe a actuellement accès.

Q10. Puis-je affecter des groupes à des unités opérationnelles à l'aide d'API ?

A10. Oui, vous pouvez assigner ou désassigner des groupes d'unités d'affaires lors de la création du groupe ou en utilisant le point de terminaison de mise à jour.

Créer Groupe...

Fournir une liste de noms abrégés d'unités commerciales dans la demande, en précisant les unités commerciales auxquelles le groupe doit avoir accès.

Mise à jour des détails du groupe

Vous pouvez soit affecter le groupe à de nouvelles unités d'entreprise, soit le supprimer des unités existantes.

  • Pour affecter le groupe à une BU : Inclure toutes les UB auxquelles le groupe devrait avoir accès, y compris celles qui lui ont été attribuées précédemment.

  • Pour supprimer l'accès à une BU : N'incluez que les UB auxquelles le groupe doit conserver l'accès. Toute BU ne figurant pas dans la liste sera supprimée de l'accès au groupe.

Remarque : Tous les utilisateurs du groupe hériteront de l'accès aux unités d'affaires assignées au groupe.

Mise à jour des détails du groupe d'utilisateurs.

Rôles et autorisations

Q11) Comment attribuer des rôles aux utilisateurs et aux groupes pour les entités et les missions ?

A11. Tout d'abord, récupérez la liste des rôles disponibles et leurs GUID à l'aide de l'API Get Role List.

Attribuer des rôles à une activité

Pour attribuer des autorisations d'accès à un utilisateur :

  • Indiquez le CWGuid de l'utilisateur, les rôles à attribuer ou à supprimer et les détails de l'objet :

    • Si le rôle s'applique à l'ensemble du système, aucune information supplémentaire n'est requise.

    • Si le rôle est spécifique à une entité ou à un engagement, indiquez le type d'objet (par exemple, entité ou engagement) et les CWGuids de ces objets.

Attribuer des rôles à une activité

Pour affecter un compte à un groupe :

  • Indiquez le CWGuid du groupe, les rôles (GUID) à attribuer ou à supprimer et les détails de l'objet :

    • Si le rôle est valable pour l'ensemble du système, aucun paramètre supplémentaire n'est nécessaire.

    • Si le rôle est spécifique à une entité ou à un engagement, indiquez le type d'objet et les CWGuids pertinents pour ces objets.

Note à l'attention des entreprises de l'unité opérationnelle (UO) : L'utilisation de CWGuids pour l'attribution des rôles améliore l'efficacité des entreprises de l'unité opérationnelle en permettant une gestion transparente des attributions de rôles entre les entités et les missions de différentes unités opérationnelles.

Missions

Q12) Des changements ont-ils été apportés aux API d'engagement ?

A12) Les API "Get Engagement" n'ont pas changé de la V1 à la V2 et continuent de fonctionner comme auparavant. Les paramètres de la demande utilisent toujours des ID, comme dans la V1. Cependant, si vous avez des intégrations existantes pour des engagements utilisant la V1, vous devrez toujours migrer vers la V2 pour assurer la continuité du support, car la V1 sera finalement obsolète.

Question spécifique à l'UB

Q13) Qu'est-ce qu'un nom abrégé de l'UB ?

A13) Chaque unité commerciale (UC) possède plusieurs attributs : une URL, un nom d'unité commerciale, un nom d'affichageet un nom abrégé d'unité commerciale. Alors que le nom de l'UB et le nom d'affichage peuvent ne pas être uniques, le nom abrégé de l'UB est unique au niveau mondial, c'est pourquoi il est utilisé comme identifiant pour les UB.

Le nom abrégé de la BU est dérivé du suffixe de l'URL de la BU et fait partie du domaine caseware. Il peut être facilement récupéré à partir de l'URL de l'UB.

Attributs de l'UB décrits

URL de la BU (non modifiable) Nom Affichage de l'étiquette Nom court
ca.caseware.ca/site-test Site d'essai Bureau-NY site d'essai
us.caseware.com/company-1-a-b Entreprise : {1} Bureau 1 (A à B) entreprise-1-a-b

Remarque importante : Actuellement, il n'existe pas d'API permettant de récupérer la liste des UB et de leurs noms abrégés. Vous pouvez consulter la liste de toutes les unités d'affaires en vous connectant au site cloud et en naviguant vers Paramètres | Unités d'affaires.

Q14) Quelle BU dois-je utiliser pour appeler des API permettant de gérer d'autres BU ?

A14) Nous vous recommandons d'utiliser l'URL de l'unité administrative (BU) pour configurer vos intégrations API et gérer les données dans d'autres BU. L'UB Admin sert de plaque tournante pour la gestion de plusieurs UB, conformément à la manière dont nous suggérons de gérer les tâches administratives dans l'interface utilisateur.

Tout comme nous conseillons aux administrateurs de gérer le personnel, les groupes et d'autres objets à partir de l'interface utilisateur Admin BU, l'utilisation de l'interface Admin BU pour vos appels API garantit la cohérence et simplifie l'administration. Cette approche vous permet d'avoir un meilleur contrôle et une meilleure visibilité lorsque vous gérez des données dans plusieurs unités fonctionnelles.