Dernière modification : 11 septembre 2025
La dernière version (2025.2) de la plateforme de développement propose un nouveau cadre de création et de déploiement basé sur des fichiers. Cette infrastructure contient la configuration d’une application, des ressources et d’autres éléments de code source. Si vous avez une application publique existante que vous avez créée avant de vous inscrire à la nouvelle version bêta de la nouvelle plateforme de développement, ce guide vous expliquera comment la migrer vers la dernière version du cadre des projets. Avant de procéder à la migration, veuillez consulter les deux sections ci-dessous concernant les fonctionnalités prises en charge et les limites.

​
Fonctionnalités d’application et extensions prises en charge

Toutes les fonctionnalités prises en charge par les projets seront incluses dans la migration, notamment :
  • Configuration de l’application
  • Webhooks
  • Actions de workflow personnalisées

​
Avant de commencer

Si votre projet existant comporte une carte avec des objets personnalisés connectés, vérifiez que vous disposez du domaine crm.objects.custom.read sur votre application avant la migration. Pour les projets créés avant la dernière version de 2025.2, les cartes d’objet personnalisé ont pu être créées avec uniquement le domaine crm.schemas.custom.read requis. Dans la dernière version (2025.2) de la plateforme de développement, crm.objects.custom.read est nécessaire pour que votre carte accède aux données des objets personnalisés.

​
Limites

Les fonctionnalités suivantes ne sont pas encore prises en charge pendant la période bêta privée actuelle :
  • La prise en charge de l’intégration GitHub, qui déclenche des chargements et des builds automatiques à partir de GitHub, n’est pas encore disponible. Si votre projet est actuellement lié à GitHub, veillez à désactiver l’intégration avant de commencer la migration. Pour désactiver l’intégration GitHub et configurer des actions GitHub pour automatiser l’intelligence conversationnelle/CD, consultez les instructions de cet article.
  • Si vous avez créé une page de paramètres pour votre application, vous devrez remanier vos paramètres à l’aide de la nouvelle fonctionnalité d’extensions d’interface utilisateur. Il est recommandé de noter tous les éléments d’interface de la version de production actuelle de votre application avant de la migrer vers la dernière version. Une fois le processus de migration terminé, vous pouvez utiliser les nouvelles fonctionnalités d’extension d’interface utilisateur pour recréer votre page des paramètres.
  • La fonctionnalité carte CRM classique n’est pas prise en charge pour les applications utilisant la dernière version des projets développeurs. Vous devrez refactoriser toutes les cartes CRM existantes pour utiliser le schéma de carte d’application à la place.
  • L’architecture des autorisations sous-jacente de votre application sera mise à jour pour prendre en charge des autorisations plus spécifiques à l’utilisateur. Dans le cadre de cette transition, un utilisateur de compte de service associé sera créé dans leur compte pour les nouvelles installations clients, qui est lié à votre application.
    • Chaque compte ne recevra désormais qu’un seul jeton d’actualisation, quel que soit le nombre d’utilisateurs individuels qui ont réautorisé l’application.
    • Les points de terminaison OAuth existants qui récupèrent les métadonnées de jeton d’actualisation et d’accès renverront toujours l’utilisateur qui l’a installé en tant que userId, et renverront désormais un serviceAccountId après la migration de votre application.

​
Migrer votre application

Une fois que vous avez examiné les considérations de la section ci-dessus, vous pouvez procéder à la migration de votre application. Ce processus préservera les informations d’authentification d’origine, les fonctionnalités de l’application et les installations pour l’application. Aucune modification n’est requise dans le backend de votre application.
  • Assurez-vous que vous avez installé la dernière version bêta de l’ILC HubSpot en exécutant la commande npm i -g @hubspot/cli@next et en la connectant à votre compte à l’aide des commandes hs auth et hs accounts use.
L’ILC doit être une version 7.5.4 ou ultérieure. Vous pouvez vérifier la version de l’ILC dont vous disposez en exécutant hs --version.
  • Pour lancer le processus de migration, utilisez l’une des commandes suivantes en fonction de l’application existante que vous migrez :
  • Si vous migrez une application héritée qui ne fait pas partie d’un projet, exécutez la commande suivante :
hs app migrate
Si vous migrez une application basée sur un projet, exécutez la commande hs project migrate.
  • Il vous sera ensuite demandé de sélectionner l’application que vous souhaitez migrer. Cela créera un nouveau projet dans votre système de fichiers local contenant une application, ainsi que ses fonctionnalités qui représentent son état actuellement configuré.
  • Après avoir sélectionné l’application, vous serez invité à confirmer les composants qui seront migrés. Assurez-vous de bien comprendre le processus de migration avant de confirmer le passage à l’étape suivante.
  • Ensuite, vous serez invité à fournir un nom de projet, un chemin local vers le nouveau projet et tous les UID requis.
Les UID doivent être utilisés comme identifiant unique pour toutes les fonctionnalités de votre application. Une fois qu’un UID est défini pour une fonctionnalité spécifique, le changer ou le modifier dans les versions ultérieures obligera la plateforme à le reconnaître comme « nouveau » ou différent des versions précédentes, ce qui pourrait ne pas être prévu.
Requêtes de migration d'une application existante
  • Une fois que vous avez confirmé les détails de votre projet, le processus de migration effectuera automatiquement les actions suivantes en une seule opération :
    • Créez un projet pour votre application dans la page Projets de votre compte, qui comprend un composant d’application et toutes les fonctionnalités compatibles.
    • Convertissez toutes les fonctionnalités existantes de l’application en fichiers de code source, que vous pourrez mettre à jour pour réviser leur configuration à l’avenir.
    • Construisez et déployez le nouveau projet (qui sera étiqueté Build #1), qui complète l’association entre l’application et son projet. Cela permettra de conserver les informations d’authentification, les fonctionnalités de l’application et les installations d’origine.
    • Téléchargez les nouveaux fichiers source du projet dans le répertoire local que vous avez spécifié précédemment lorsque vous y êtes invité dans le terminal.
    • Si un projet existant a été migré, déplacez les fichiers du répertoire d’origine src/ vers archive/ et renseignez /src/ avec le nouveau code source du projet.
Page de détails de l'application migrée dans la vue Projets
La build #1 du nouveau projet capture l’état de configuration de l’application pour toutes les fonctionnalités prises en charge comme base à laquelle vous pouvez revenir. Si nécessaire, vous pouvez annuler en toute sécurité toute modification future de ce projet (par exemple, l’ajout de cartes d’application basées sur React) en redéployant la build #1.
Après la migration, les fonctionnalités définies dans le code source du projet ne pourront plus être modifiées via l’interface utilisateur de gestion des applications dans HubSpot, ni via les anciennes API de développeur. D’autres fonctionnalités (par exemple, les actions de workflow personnalisées ou les événements de chronologie) continueront d’être gérées avec leurs API respectives.
  • La migration étant terminée, comme indiqué dans le champ "platformVersion": "2025.2" de votre fichier hsproject.json, vous pouvez commencer à développer des fonctionnalités nouvelles ou existantes en utilisant l’ILC HubSpot et les fichiers de code source de votre projet.