Cette série de tutoriels vidéo d’Autodesk® Developer détaille la création d’une application web Node.js utilisant l’API ACC Issues pour gérer les problèmes de construction. Le formateur explique comment configurer l’environnement de développement, établir l’authentification sécurisée à trois étapes et structurer les services pour explorer les projets. Les sources démontrent concrètement l’utilisation du SDK Autodesk® pour extraire, filtrer et afficher des données complexes, telles que les attributs personnalisés et les causes racines. Une interface utilisateur est mise en place pour permettre la visualisation des données sous forme de tableaux, ainsi que l’importation et l’exportation de fichiers CSV. L’objectif final est de fournir aux développeurs les compétences nécessaires pour automatiser le suivi des incidents au sein d’Autodesk® Construction Cloud.
Cliquez en haut à droite de la vidéo pour afficher les suivantes 
Synthèse Technique : Maîtrise de l’API Issues d’Autodesk® Construction Cloud (ACC)
1. Introduction et Objectifs Stratégiques de l’API Issues
L’API Issues d’Autodesk® Construction Cloud (ACC) représente le socle de l’interopérabilité pour la gestion de la qualité et de la sécurité sur les chantiers numériques. En tant qu’architecte, maîtriser cette API ne consiste pas seulement à manipuler des points de terminaison, mais à orchestrer la transformation de données de terrain brutes en leviers décisionnels structurés. L’objectif stratégique est la centralisation des métadonnées critiques (titre, statut, cause racine), la validation via des attributs personnalisés et l’automatisation des flux de reporting.
Périmètre technique et limites critiques : Une compréhension rigoureuse des capacités actuelles de l’API est indispensable pour le scoping de projet :
- Capacités opérationnelles : Récupération et mutation des données générales, gestion granulaire des types/sous-types, exploitation des
Root Causeset des commentaires. - Limites et roadmap :
- Les Webhooks pour les Issues sont disponibles mais requièrent une implémentation d’écouteur distincte.
- Les Pushpins (punaises de localisation spatiale sur documents) ne sont pas encore exposés via l’API, bien que leur versionnage soit imminent.
- La gestion des pièces jointes complexes et des références (photos, documents) est supportée par l’API Issues, mais sa complexité structurelle nécessite souvent des workflows dédiés hors du cadre d’un simple import CSV.
- L’utilisation du Viewer Autodesk® est dissociée de la gestion purement logique des données via l’API Issues.
Cette délimitation technique impose une configuration initiale sans faille pour garantir la communication entre votre middleware et l’écosystème APS.
2. Configuration de l’Application et Provisionnement du Compte
L’accès aux données client repose sur le Provisioning, une étape de confiance mutuelle où l’ID de l’application est explicitement autorisé sur le Hub ACC. Sans ce lien contractuel technique, toute requête, même authentifiée, se soldera par un échec d’accès.
Architecture de Configuration APS (Autodesk® Platform Services) : Le développeur doit configurer une « Traditional Web App » sur le portail APS. La gestion du Client ID et du Client Secret est primordiale ; ces derniers doivent être injectés via des variables d’environnement sécurisées (fichiers .env pour Node.js ou appsettings.json pour .NET).
Gouvernance et Environnements :
- Rôle de l’Admin de compte : Seul un Account Admin peut finaliser l’intégration. Dans l’onglet « Custom Integrations », l’ID de l’application doit être lié au Hub pour déverrouiller les services. Notez que l’utilisation d’un compte Robot (SSA) peut simplifier la gestion des permissions à l’échelle de l’entreprise.
- Fondations logicielles :
- En .NET 8, l’architecture repose sur l’unité
Autodesk.SDKManager, servant de base aux packages NuGet spécifiquesAutodesk.Construction.Issues(beta 2) etAutodesk.Construction.AccountAdmin. - En Node.js, l’utilisation du SDK TypeScript/Node est recommandée pour une gestion asynchrone fluide des promesses.
- En .NET 8, l’architecture repose sur l’unité
Une fois ces fondations établies, l’architecture de sécurité peut être déployée pour régir les accès utilisateurs.
3. Architecture d’Authentification : Flux Three-Legged et SSA
Pour l’API Issues, le flux Three-Legged OAuth est la norme, car il garantit que les actions sont effectuées sous le contexte et les permissions d’un utilisateur réel. Toutefois, pour les automatisations de serveur à serveur, le concept de SSA (Service-to-Service Account) / Robot User émerge comme une solution moderne pour contourner les contraintes d’expiration des jetons.
Mécanismes et Sécurité :
- Access vs. Refresh Token : Le jeton d’accès expire après 60 minutes. L’implémentation d’un mécanisme de rafraîchissement automatique via le
Refresh Tokenest critique pour maintenir la continuité de service sans intervention utilisateur. - Approches de développement :
- .NET : La gestion s’appuie généralement sur un contrôleur gérant les cookies de session pour persister les états d’authentification.
- Node.js : L’utilisation d’un middleware (ex:
APS.js) permet d’intercepter les requêtes pour valider et rafraîchir le jeton avant l’appel aux SDK.
- Scopes requis : La manipulation des Issues exige les scopes
data:read,data:writeetaccount:read.
L’obtention d’un jeton valide permet alors d’initier la navigation dans la hiérarchie complexe des données Autodesk®.
4. Exploration de la Hiérarchie : Le Piège du Préfixe « b. »
L’accès aux Issues nécessite d’abord de naviguer via la Data Management API pour identifier la structure : Hubs > Projets. C’est ici que réside l’un des « gotchas » les plus fréquents pour les développeurs ACC.
Navigation et Précision Technique : Le développeur doit lister les Hubs et filtrer les projets pour extraire le Project ID. Une attention particulière doit être portée au format de cet identifiant : alors que la Data Management API renvoie souvent des IDs de projet préfixés par « b. » (héritage de BIM 360), l’API Issues d’ACC rejette systématiquement ce préfixe. Il est impératif de nettoyer le GUID (ex: extraire 1234... de b.1234...) pour éviter des erreurs 404 ou 400 lors des appels aux endpoints spécifiques aux Issues ou à l’Account Admin. L’utilisation des versions Bêta des SDK est indispensable pour garantir la compatibilité avec ces endpoints de nouvelle génération.
L’obtention d’un GUID de projet propre est la condition sine qua non pour interroger les paramètres granulaires du service Issues.
5. Manipulation Avancée des Issues : Schémas et Performance
Les Issues ne sont pas de simples chaînes de caractères ; ce sont des objets riches liés à des dictionnaires de configuration globaux. Une intégration réussie doit impérativement traiter la pagination pour gérer les volumes importants et respecter le Rate Limiting (Error 429).
Logique de l’API Settings et Schémas : Avant toute création, il est crucial d’interroger l’API Settings pour récupérer les IDs de référence :
- Subtypes & Root Causes : Ces métadonnées valident la cohérence des données injectées.
- Custom Attribute Definitions : Essentiels pour mapper les champs spécifiques à l’entreprise.
- Assignee Logic : L’API supporte une logique d’assignation complexe (
assignedToetassignedToType) permettant de cibler un Utilisateur, un Rôle ou une Entreprise.
Champs critiques pour l’Import/Export : Pour un workflow robuste, les champs suivants doivent être traités : title, description, subtypeId, status, assignedTo, assignedToType, rootCauseId, et dueDate. La maîtrise de ces IDs de configuration permet de transformer ces données techniques en outils métier via l’interface utilisateur.
6. Architecture UI et Workflows d’Import/Export CSV
La valeur ajoutée d’une application APS réside dans sa capacité à aplatir la complexité du JSON pour l’utilisateur final. L’architecture UI recommandée sépare la navigation (Sidebar) de l’exploitation des données (Data Grid).
Composants et Connectivité :
- Inspire Tree : Utilisé pour la sidebar, ce composant gère efficacement la hiérarchie Hubs/Projets.
- Bootstrap Table : Idéal pour le rendu des Issues, il permet de « view-port » de grands ensembles de données et de gérer des objets imbriqués (comme les attributs personnalisés).
- Flux de données : Les scripts clients (
table.js,main.js) communiquent avec les endpoints backend, assurant une réactivité dynamique sans rechargement de page.
Logique d’Import/Export CSV :
- Export : Le JSON est transformé en un objet Blob CSV pour permettre le reporting hors ligne.
- Import/Patch (Create vs Update) : L’algorithme de décision repose sur la présence de l’ID. Si la ligne CSV contient un GUID, l’application exécute un
PATCH(mise à jour) ; si l’ID est absent, unPOST(création) est initié.
Cette maîtrise technique complète, du provisionnement à l’interface, permet d’envisager des automatisations futures comme l’intégration de Webhooks pour une synchronisation en temps réel ou la gestion automatisée des pièces jointes, consolidant ainsi la maturité numérique de vos workflows de construction.