Documentation technique

Accueil / Documentation technique / Flux v1 / Exports (JSON / XML) (v1) / Notification, traitement, confirmation (v1)

Notification, traitement, confirmation (v1)

Notification, récupération et traitement

Notification par e-mail

Les e-mails de notification sont envoyés automatiquement aux adresses indiquées dans la configuration des exports :

  • lorsqu’une erreur se produit au cours d’un export (périodique ou ponctuel). Ce message reprend les informations principales concernant la tâche d’export.
  • lorsqu’un export ponctuel se termine avec succès. Ce message reprend les informations principales concernant la tâche d’export et inclut l’URL à laquelle le fichier d’export peut être récupéré.

Notification par web service

Dès qu’un export se termine, avec succès ou en erreur, l’application Apidae peut notifier un web service de votre choix. Pour cela, il faut définir l’URL du web service dans la configuration de l’export.

La notification est faite via une requête de type POST contenant les informations suivantes :

  • siteWebId : un entier. C’est l’identifiant du projet concerné.
  • statut : une chaine de caractères, ‘SUCCESS’ ou ‘ERROR’. C’est l’issue de l’export.
  • ponctuel : un booléen. Indique si l’export est ponctuel (true) ou périodique (false).
  • reinitialisation : un booléen. Indique si l’export est une réinitialisation (true) ou différentiel (false).

Dans le cas où la plate-forme Apidae est soumise à une erreur de fonctionnement globale pendant le traitement des exports périodiques, nous pouvons être amenés à déclencher de manière massive des exports ponctuels (différentiels) pour suppléer à la panne. Si vous choisissez de ne pas les intégrer automatiquement, ils vous appartient de programmer le rattrapage de l’export non intégré (en planifiant une réinitialisation par exemple).

Deux informations sont ajoutées en cas de succès (si le fichier d’export est disponible) :

  • urlRecuperation : une chaine de caractères. L’URL de récupération du fichier d’export.
  • urlConfirmation : une chaine de caractères. L’URL de confirmation.

Cette notification (effectuée par le serveur Apidae sur votre url de notification) possède un timeout de 30 secondes. Si votre web service ne traite pas la notification avant que le timeout soit écoulé, la notification est marquée comme échouée.
Votre web-service récepteur de la notification ne doit donc pas traiter l’import pendant qu’il répond à la notification (cela dépasserait sûrement les 30 secondes), il doit seulement stocker les informations transmises pour procéder à l’import (téléchargement et traitement du fichier) par la suite.

Pour les raisons détaillées précédemment :
Le téléchargement de l’archive d’export et / ou la confirmation de l’intégration ne doivent pas être réalisés pendant le traitement de la notification.
Le mode de fonctionnement préconisé est d’enregistrer les informationsi fournies par la notification, et de réaliser les tâches d’import et de confirmation par une tâche cron qui exploite les informations enregistrées lors de de la notification.

Récupération du fichier d’export

Dès qu’un export est terminé, l’archive ZIP contenant les informations exportées est immédiatement mise à disposition. Pour récupérer ce fichier il existe actuellement deux moyens simples :

  • Télécharger directement le fichier via l’URL de récupération, disponible dans la notification par web-service et dans l’e-mail de notification pour les exports ponctuels. C’est la solution à priviligier pour automatiser la récupération de l’archive d’export.
  • Se connecter à Apidae et récupérer et télécharger l’archive sur la page dédiée à cette tâche d’export (Diffuser > Projets > Mes Projets > projet > onglet Calcul et sélections, cliquer sur la tâche correspondante et télécharger l’archive via le lien dans la fiche de la tâche). Cette méthode peut être utilisée pour les développements ou des besoins ponctuels.

Temps de rétention des fichiers

Un nettoyage est effectué régulièrement pour supprimer les fichiers d’export considérés comme trop vieux. Par sécurité on conserve systématiquement les 5 derniers exports pour chaque projet. Pour les fichiers supplémentaires, la politique de suppression dépend de la fréquence d’export :

  • Pour une fréquence d’export quotidienne, on supprime les exports qui datent de plus de 5 jours,
  • Pour une fréquence d’export hebdomadaire, on supprime les exports qui datent de plus de 5 semaines,
  • Pour une fréquence d’export mensuelle, on supprime les exports qui datent de plus de 5 mois.

Confirmation d’intégration de l’export

L’URL de confirmation envoyée dans la notification de fin d’export est un lien permettant de confirmer que le fichier d’export a bien été récupéré par le prestataire.Une fois le fichier récupéré, il est impératif de contacter cette URL pour que la confirmation soit faite du côté Apidae.

Il n’est pas possible d’effectuer la confirmation d’intégration dans le script qui répond à la notification. La confirmation doit être réalisée après avoir répondu à la notification et après avoir intégré les contenus.

Attention, trop d’exports non confirmés peuvent être interprétés comme une absence d’utilisation des exports et mener à une désactivation de vos exports par les administrateurs de Apidae.

S’il a été confirmé, l’export apparait dans la liste des tâches d’export (interfaces du membre et dev-tools) de l’application avec un fond vert sous le statut « Généré et intégré » (au lieu de « Généré »).