API REST Alfresco : construire une intégration métier fiable

Connecter un ERP, un portail client ou une application métier à Alfresco ne consiste pas seulement à envoyer des fichiers vers une API. L’intégration doit aussi préserver les métadonnées, respecter les droits, éviter les doublons et permettre une reprise propre après incident.

Une démonstration peut fonctionner avec quelques appels HTTP. Un flux de production doit, lui, rester compréhensible et récupérable lorsque le réseau coupe, qu’un document est déjà présent ou qu’une règle métier refuse l’opération. Voici les décisions à prendre avant de développer.

Quand utiliser l’API REST native d’Alfresco ?

L’API REST d’Alfresco Content Services couvre les opérations courantes sur le dépôt : consulter et créer des nœuds, gérer des dossiers et des fichiers, rechercher du contenu, manipuler les utilisateurs ou exploiter les journaux d’audit. Elle convient bien lorsqu’une application doit piloter précisément des documents et leurs propriétés.

Elle ne remplace pas tous les autres mécanismes d’intégration :

• CMIS reste pertinent lorsqu’une application doit rester portable entre plusieurs solutions documentaires ;
• les Web Scripts servent à exposer une opération métier spécifique qui n’existe pas dans l’API standard ;
• les événements sont utiles pour réagir à des changements sans interroger continuellement le dépôt ;
• les workflows structurent une validation humaine ou un processus documentaire durable.

Le premier choix d’architecture consiste donc à vérifier si l’API standard répond déjà au besoin. Créer une extension pour une opération native ajoute inutilement du code à maintenir.

Définir le contrat documentaire avant les endpoints

Une intégration fiable commence par un contrat clair entre le système source et Alfresco. Pour chaque type de document, précisez :

• l’identifiant métier stable, par exemple un numéro de facture ou de dossier ;
• le type et les aspects Alfresco attendus ;
• les propriétés obligatoires, leur format et leur référentiel ;
• le dossier cible et sa règle de nommage ;
• les groupes autorisés à lire, modifier ou valider le contenu ;
• la règle applicable à une nouvelle version, à un remplacement et à une suppression ;
• le système qui fait foi pour chaque donnée.

Sans ce contrat, le connecteur finit souvent par reproduire l’arborescence du système source, stocker des métadonnées incomplètes et distribuer des permissions difficiles à auditer.

Rendre chaque opération idempotente

Une opération idempotente peut être rejouée sans créer un second résultat incohérent. Cette propriété est essentielle : un client peut ne pas recevoir la réponse d’Alfresco alors que le document a bien été créé.

La stratégie la plus robuste consiste à conserver un identifiant métier unique dans une propriété indexée, puis à vérifier cet identifiant avant toute création. Selon le cas, le connecteur peut ensuite :

1. créer le document s’il n’existe pas ;
2. ajouter une version si le contenu a changé ;
3. mettre à jour uniquement les métadonnées autorisées ;
4. ignorer la demande si l’état cible est déjà atteint ;
5. placer le message en erreur fonctionnelle si plusieurs documents portent le même identifiant.

Le nom du fichier seul ne constitue pas une clé fiable. Il peut changer, être réutilisé ou contenir une variation sans valeur métier.

Séparer erreurs techniques et erreurs fonctionnelles

Toutes les erreurs ne doivent pas être rejouées de la même manière.

Une coupure réseau, un délai dépassé ou une indisponibilité temporaire peut justifier une nouvelle tentative avec un délai progressif. À l’inverse, une métadonnée obligatoire absente, un type documentaire inconnu ou un refus d’autorisation nécessite une correction, pas une boucle de tentatives.

Pour chaque appel, journalisez au minimum :

• un identifiant de corrélation partagé entre l’application et le connecteur ;
• l’opération demandée et l’identifiant métier concerné ;
• le statut HTTP et la catégorie d’erreur ;
• le nombre de tentatives et la prochaine échéance ;
• l’identifiant du nœud Alfresco lorsqu’il existe ;
• la durée de traitement, sans enregistrer le contenu du document ni un jeton d’accès.

Cette séparation accélère le diagnostic et évite qu’une file de messages bloque sur une erreur qui ne disparaîtra jamais seule.

Respecter les droits sans utiliser un compte tout-puissant

Un compte administrateur masque les défauts de conception et augmente l’impact d’une compromission. Le compte technique doit disposer du périmètre minimal nécessaire. Les droits documentaires doivent ensuite être appliqués à des groupes métier stables, plutôt qu’à une accumulation d’utilisateurs individuels.

Avant la mise en production, testez au moins quatre situations :

• un document autorisé est créé au bon emplacement ;
• un document hors périmètre est refusé ;
• un utilisateur métier voit uniquement ce qu’il doit voir ;
• les journaux ne révèlent ni secret ni donnée documentaire sensible.

L’authentification et la gestion des jetons dépendent de la version et de l’architecture Alfresco retenues. Elles doivent être validées avec la documentation correspondant exactement à l’instance cible.

Limiter les volumes et maîtriser la pagination

Une intégration ne doit pas supposer qu’une liste tient dans une seule réponse. Les recherches et parcours de dossiers doivent gérer la pagination et arrêter explicitement le traitement à la fin des résultats.

Pour les reprises volumineuses, préférez des lots bornés, un curseur de reprise et un débit contrôlé. Mesurez séparément le temps d’envoi du binaire, le traitement des métadonnées et l’indexation. Une réponse HTTP réussie ne garantit pas nécessairement que le document est déjà disponible dans tous les parcours de recherche.

Mettre en place les indicateurs qui permettent d’agir

Un tableau de bord utile ne se limite pas au nombre d’appels réussis. Il doit montrer :

• le volume traité et le débit par flux ;
• le taux d’erreurs techniques et fonctionnelles ;
• l’âge du plus ancien message en attente ;
• le nombre de doublons évités ou détectés ;
• le délai entre réception, dépôt et disponibilité métier ;
• les rejets par règle ou par type de document.

Ajoutez une alerte sur une dérive durable plutôt que sur chaque erreur isolée. L’équipe doit pouvoir retrouver le document concerné à partir de l’identifiant de corrélation, puis relancer uniquement l’opération sûre.

Recette : huit scénarios à exécuter avant la bascule

1. Création nominale avec toutes les métadonnées.
2. Rejeu strict de la même demande sans doublon.
3. Ajout d’une nouvelle version du contenu.
4. Métadonnée obligatoire absente.
5. Droit insuffisant sur le dossier cible.
6. Coupure après création, avant réception de la réponse.
7. Indisponibilité temporaire d’Alfresco puis reprise.
8. Recherche et rapprochement d’un document déjà existant.

La recette doit vérifier le résultat dans Alfresco, mais aussi la trace laissée dans le système source, le connecteur et les outils de supervision.

De la preuve de concept à une intégration exploitable

Une API REST facilite la connexion technique ; elle ne remplace pas le cadrage documentaire. La fiabilité vient d’un contrat de données explicite, d’opérations rejouables, de droits minimaux et d’une supervision pensée pour la reprise.

Rainbow Integration peut auditer un flux existant ou cadrer une nouvelle intégration Alfresco : modèle documentaire, choix d’API, stratégie de reprise, sécurité et critères de recette.

Présentez-nous votre flux, vos volumes et le résultat métier attendu.