Skip to main content
Le Rapport sur le traitement métier indique la qualité de traitement des documents et fournit une traçabilité des transactions de bout en bout pour les besoins d’audit. Le Warehouse enregistre toutes les transactions (terminées ou en cours) pour l’analyse et la visualisation dans des outils de business intelligence. Les données sont conservées pendant 12 mois, ce qui permet l’analyse et l’audit sur des périodes de temps définies. Les données suivantes sont suivies :
  • ID de transaction.
  • ID de Skill et version.
  • Chemin de traitement par étapes :
    • Types d’étapes
    • Noms
    • Date et heure de début et de fin de l’étape
    • Durée (en secondes)
  • Nom et e-mail de l’opérateur de relecture manuelle.
  • Paramètres d’enregistrement du document et de la transaction.
Le Warehouse ne stocke pas d’informations sur les événements de traitement des documents dans les activités qui ne sont jamais exécutées selon leur configuration. Par exemple, le paramètre « Assemble by files » correspond au comportement par défaut de Vantage ; par conséquent, le traitement des documents dans cette activité sera ignoré dans un workflow.

​
Comprendre les différences de comportement entre v1 et v2

Avant la migration, il est important de comprendre que v1 et v2 ne diffèrent pas uniquement par la structure de l’API : elles définissent différemment la période de déclaration, et ce, intentionnellement. Attendez-vous à des totaux différents lorsque vous comparez les deux versions, et pas seulement à un format de requête/réponse différent. v1 filtre par transaction, puis renvoie toutes les étapes de ces transactions. Si les étapes d’une transaction chevauchent, même partiellement, la fenêtre de filtrage startDate/endDate, toutes ses étapes sont renvoyées, y compris celles terminées plusieurs semaines avant startDate ou après endDate. v2 filtre par étape. Seules les étapes dont l’horodatage CompletedUtc se situe dans la fenêtre startDate/endDate sont renvoyées ; les autres étapes de la transaction sont exclues, même si d’autres étapes de cette même transaction se situent dans la fenêtre.

​
Requêtes synchrones et asynchrones

La v1 consiste en un unique appel synchrone : vous envoyez une requête GET avec des paramètres de requête et recevez directement les données du rapport dans la réponse. La v2 utilise quant à elle un modèle asynchrone : vous soumettez une requête, interrogez son statut, puis téléchargez les résultats une fois le rapport prêt. Ce changement permet à la v2 de traiter des requêtes de données bien plus volumineuses sans expirer. La v1 est obsolète, mais les clients peuvent continuer à l’utiliser ; aucune date de retrait n’est actuellement prévue.

​
Portée de la période de déclaration

Les points de terminaison v1 et v2 définissent différemment la période de déclaration. Il s’agit du comportement attendu, et non d’un bug, mais cela signifie que les totaux des deux points de terminaison (ou des rapports v2 utilisant des plages de dates différentes) ne sont pas directement comparables.
  • v1 renvoie toutes les étapes appartenant à toute transaction active au cours de la période demandée, y compris les étapes survenues en dehors des dates de début et de fin de cette période. Par exemple, si une transaction a commencé avant le début de la période ou s’est terminée après sa fin, v1 renvoie tout de même toutes les étapes de cette transaction.
  • v2 renvoie uniquement les étapes réellement survenues au cours de la période demandée. Les étapes situées en dehors de la fenêtre startDate/endDate sont exclues, même si elles appartiennent à une transaction qui se situe partiellement dans la période.
Par conséquent, la migration de v1 vers v2 peut produire des totaux inférieurs ou différents pour une même plage de dates nominale, car v2 n’inclut plus les étapes situées en dehors de la fenêtre.
Comme v2 filtre selon la valeur CompletedUtc de chaque étape, chaque étape appartient à une seule fenêtre temporelle, quelle que soit la façon dont vous découpez la plage : un ensemble de rapports quotidiens donnera le même total qu’un rapport couvrant la plage équivalente sur plusieurs jours. Il s’agit d’une amélioration importante par rapport à v1, où l’inclusion d’une étape dépend du fait que sa transaction était active pendant la fenêtre, et non de l’heure d’achèvement de l’étape elle-même. Les totaux de v1 ne sont donc pas nécessairement les mêmes selon le découpage de la plage. Un point à garder à l’esprit avec v2 : les étapes d’une transaction qui s’étendent sur deux jours apparaîtront dans deux rapports quotidiens différents, un pour chaque jour, au lieu d’être toutes regroupées dans l’un ou l’autre.

​
Le filtrage par date repose sur completedUtc

Dans le point de terminaison v2, startDate et endDate filtrent tous deux selon l’horodatage CompletedUtc propre à chaque étape, et non selon une heure de début ou de fin au niveau de la transaction. Chaque étape d’une transaction (par exemple, Input, Classification, Extraction, relecture manuelle, Output) ayant sa propre valeur CompletedUtc, les étapes d’une même transaction peuvent être réparties sur différentes dates. Chaque étape est évaluée, puis incluse ou exclue indépendamment, uniquement en fonction de sa propre heure de fin. Si une étape de transaction est retraitée, corrigée, repasse par la relecture manuelle ou fait l’objet d’une nouvelle tentative, pour quelque raison que ce soit, son CompletedUtc est mis à jour avec la nouvelle heure de fin. Dans la v2, cela n’affecte les résultats que lorsque la valeur endDate de la requête se situe dans le futur, c’est-à-dire lorsque la fenêtre est encore ouverte. Une fois que la valeur endDate d’une requête est passée, ses résultats sont stables : le retraitement horodate une étape avec l’heure actuelle, qui, par définition, est postérieure à une fenêtre déjà fermée ; elle ne peut donc pas y entrer ou en sortir rétroactivement.

​
Des étapes en cours peuvent apparaître dans les résultats

Un export peut inclure des étapes qui ne sont pas encore terminées. Si, au moment où le rapport est généré, une transaction comporte une étape toujours en cours (par exemple, avec le statut Processing ou WaitingForManualReview), cette étape peut tout de même apparaître dans les résultats avec son statut en cours et sans valeur CompletedUtc, à condition qu’une autre partie de la transaction relève de la période demandée. Cela signifie qu’un même export peut combiner des étapes finalisées (avec une valeur CompletedUtc comprise dans la période) et des étapes en attente (sans aucun horodatage de fin). Vérifiez la colonne Status de chaque ligne au lieu de supposer que chaque étape renvoyée représente un événement terminé. Un besoin courant consiste à générer un rapport sur les transactions de la veille. Utilisez v2 à cette fin, avec startDate et endDate définis sur la plage UTC allant de 00:00:00 à 23:59:59 de la veille. Comme v2 filtre selon le CompletedUtc propre à chaque étape, il renvoie exactement les étapes terminées ce jour-là, ce qui permet d’obtenir des totaux cohérents d’un jour à l’autre. Évitez d’utiliser v1 à cette fin. Comme v1 renvoie chaque étape de toute transaction active pendant la période, une transaction comportant des étapes terminées des semaines avant ou après le jour ciblé est tout de même renvoyée dans son intégralité, incluant ainsi des étapes sans rapport dans des chiffres qui devraient concerner une seule journée. Un compromis à prendre en compte avec l’approche v2 : les étapes d’une transaction qui chevauche minuit seront réparties entre deux rapports quotidiens, un pour chaque jour, au lieu d’apparaître entièrement dans l’un ou l’autre. Ce comportement est attendu ; voir la portée de la période de déclaration ci-dessus. Tant que endDate correspond à un jour déjà entièrement écoulé, le rapport est stable et reproductible : l’exécution ultérieure de la même requête renvoie les mêmes résultats. En revanche, si vous interrogez une plage incluant la journée en cours, les résultats peuvent changer d’une exécution à l’autre à mesure que d’autres étapes se terminent (voir Le filtrage par date est basé sur CompletedUtc ci-dessus).

​
Migration de v1 vers v2

​
Quoi de neuf ?

Dans la requête (/api/reporting/v2/exports/transaction-steps) :
  • Les filtres ont été déplacés des paramètres de requête vers le corps de la requête (objet JSON filters).
  • startDate, spécifié dans l’objet filters, est désormais obligatoire.
  • Nouveau champ : sendEmailNotification (true/false) - envoie un e-mail à l’utilisateur ayant demandé le rapport lorsque celui-ci est prêt à être téléchargé.
Dans les fichiers CSV téléchargés du résultat final (/api/reporting/v2/exports/transaction-steps/{{requestId}}/result/{fileIndex}), deux colonnes ont été ajoutées :
  • DocumentsCount : le nombre de documents traités dans une transaction.
  • PagesCount : le nombre de pages traitées dans une transaction.

​
Différences d’utilisation de l’API

v1 utilise une seule requête GET avec des paramètres de requête et renvoie directement le rapport. v2 déplace les filtres vers le corps d’une requête POST, puis divise le processus en trois appels : demander le rapport, interroger périodiquement son statut et télécharger les résultats une fois qu’il est prêt. Poursuivez votre lecture pour en savoir plus sur le fonctionnement du point de terminaison v2 ci-dessous.

​
Téléchargement d’un rapport de données

Seuls les utilisateurs ayant les rôles Tenant Administrator et Processing Supervisor peuvent télécharger un rapport de données depuis le Warehouse. Pour plus d’informations, consultez Contrôle d’accès fondé sur les rôles (RBAC).
Vous pouvez obtenir des données du Warehouse dans un fichier CSV à l’aide de l’API Vantage. Pour ce faire, envoyez une requête POST à la ressource suivante : Un corps de requête doit inclure les propriétés suivantes dans un objet filters :
  • skillId. L’ID du Skill dont les transactions doivent être téléchargées. Facultatif.
  • transactionId. L’ID de la transaction à utiliser pour le filtrage. Facultatif.
  • startDate. Le premier jour de la période (format d’exemple : 2022-01-07T13:03:38, l’heure doit être en UTC) pour laquelle les transactions doivent être téléchargées. Filtre selon l’horodatage CompletedUtc de chaque étape. Obligatoire.
  • endDate. Le dernier jour de la période (format d’exemple : 2022-09-07T13:03:38, l’heure doit être en UTC) pour laquelle les transactions doivent être téléchargées. Filtre selon l’horodatage CompletedUtc de chaque étape. Facultatif.
  • sendEmailNotification. Envoyer un e-mail à l’utilisateur qui a créé la demande de rapport pour l’informer que le rapport est prêt à être téléchargé. Facultatif.
Les demandes de rapport sont exécutées de manière asynchrone, ainsi la réponse renvoie un requestId utilisé pour vérifier l’état de la requête. Résultat :
Pour vérifier l’état du rapport, incluez le requestId dans la requête GET : Une fois le rapport créé, le status a la valeur “Succeeded” et totalFileCount indique le nombre de fichiers disponibles au téléchargement :
Pour télécharger les fichiers de rapport générés, effectuez une requête GET vers l’URL suivante, en transmettant de nouveau le requestId et en ajoutant le fileIndex, l’index de base zéro du fichier. Par exemple, si "totalFileCount": 3, alors les index de fichier disponibles seraient 0, 1 et 2. Voici un exemple de réponse CSV :

​
Structure de la réponse

Chaque ligne d’un fichier CSV correspond à une opération effectuée sur une transaction, par exemple l’importation de documents, la reconnaissance ou la revue manuelle. Pour chaque opération dans le Warehouse, ses détails sont stockés dans des colonnes : Les données préparées sont stockées pendant 2 semaines après l’exécution de la requête. Les données obtenues au format CSV peuvent ensuite être analysées dans n’importe quel outil de Business Intelligence (BI).

​
Récupération de la liste des demandes de rapport

Pour récupérer la liste des demandes de rapport effectuées sur une période donnée, effectuez une requête GET vers le point de terminaison suivant, où createdFrom et createdTo représentent la plage de dates et statusFilter est l’une des valeurs suivantes : New,Queued,Processing,Succeeded,Failed, ou Cancelled. Cette opération est utile si vous avez égaré des identifiants de demande. La réponse contient un tableau de requêtes de reporting.