Skip to main content
Berichte zur Geschäftsverarbeitung zeigen, wie gut Dokumente verarbeitet werden, und bieten eine durchgängige Vorgangsverfolgung für Prüfzwecke. Das Warehouse erfasst alle Vorgänge (abgeschlossene und laufende) zur Analyse und Visualisierung in Business-Intelligence-Tools. Die Daten werden 12 Monate lang aufbewahrt, wodurch Analysen und Prüfungen über definierte Zeiträume hinweg möglich sind. Die folgenden Daten werden nachverfolgt:
  • Vorgangs-ID.
  • Skill-ID und -Version.
  • Verarbeitungsweg nach Schritten:
    • Schritttypen
    • Namen
    • Datum und Uhrzeit des Beginns und Endes des Schritts
    • Dauer (in Sekunden)
  • Name und E-Mail-Adresse des Operators für die Manuelle Überprüfung.
  • Dokument- und Vorgangsregistrierungsparameter.
Das Warehouse speichert keine Informationen über Ereignisse der Dokumentverarbeitung in Aktivitäten, die gemäß ihren Einstellungen niemals ausgeführt werden. Beispielsweise entspricht die Einstellung Assemble by files dem Standardverhalten von Vantage, daher wird die Dokumentverarbeitung in dieser Aktivität in einem Workflow übersprungen.

​
Unterschiede im Verhalten von v1 und v2 verstehen

Vor der Migration ist es wichtig zu verstehen, dass sich v1 und v2 nicht nur in der Form der API unterscheiden: Sie definieren den Berichtszeitraum absichtlich unterschiedlich. Rechnen Sie beim Vergleich der beiden Versionen mit unterschiedlichen Summen, nicht nur mit einem anderen Anfrage-/Antwortformat. v1 filtert nach Vorgängen und gibt dann jeden Schritt dieser Vorgänge zurück. Wenn die Schritte eines Vorgangs das Filterfenster startDate/endDate auch nur teilweise überschneiden, werden alle Schritte dieses Vorgangs zurückgegeben, einschließlich derjenigen, die Wochen vor startDate oder nach endDate abgeschlossen wurden. v2 filtert nach Schritten. Es werden nur die einzelnen Schritte zurückgegeben, deren eigener Zeitstempel CompletedUtc innerhalb des Fensters startDate/endDate liegt; die übrigen Schritte des Vorgangs werden ausgeschlossen, auch wenn andere Schritte desselben Vorgangs innerhalb des Fensters liegen.

​
Synchrone und asynchrone Anfragen

v1 ist ein einzelner synchroner Aufruf: Sie senden eine GET-Anfrage mit Abfrageparametern und erhalten die Berichtsdaten direkt in der Antwort. v2 verwendet dagegen ein asynchrones Modell: Sie senden eine Anfrage, fragen deren Status ab und laden die Ergebnisse herunter, sobald der Bericht bereit ist. Dadurch kann v2 wesentlich größere Datenanfragen verarbeiten, ohne dass Zeitüberschreitungen auftreten. v1 ist veraltet, kann von Kunden jedoch weiterhin verwendet werden; derzeit ist kein Termin für die Einstellung geplant.

​
Umfang des Berichtszeitraums

Die Endpunkte v1 und v2 definieren den Berichtszeitraum unterschiedlich. Dieses Verhalten ist beabsichtigt und kein Fehler. Daher sind die Summen der beiden Endpunkte (oder von v2-Berichten mit unterschiedlichen Datumsbereichen) nicht direkt vergleichbar.
  • v1 gibt alle Schritte zurück, die zu einem Vorgang gehören, der während des angeforderten Zeitraums aktiv war, einschließlich der Schritte, die außerhalb des Start- und Enddatums des Zeitraums erfolgten. Wenn ein Vorgang beispielsweise vor Beginn des Zeitraums gestartet oder nach dessen Ende abgeschlossen wurde, gibt v1 dennoch jeden Schritt dieses Vorgangs zurück.
  • v2 gibt nur die Schritte zurück, die tatsächlich innerhalb des angeforderten Zeitraums erfolgten. Schritte außerhalb des Fensters startDate/endDate werden ausgeschlossen, selbst wenn sie zu einem Vorgang gehören, der teilweise innerhalb des Zeitraums liegt.
Daher kann die Migration von v1 zu v2 für denselben nominellen Datumsbereich zu niedrigeren oder abweichenden Summen führen, da v2 keine Schritte mehr einschließt, die außerhalb des Fensters liegen.
Da v2 nach dem jeweiligen CompletedUtc eines Schritts filtert, gehört jeder Schritt genau zu einem Zeitfenster – unabhängig davon, wie Sie den Bereich aufteilen: Eine Reihe täglicher Berichte ergibt dieselbe Summe wie ein Bericht über den entsprechenden mehrtägigen Zeitraum. Dies ist eine wesentliche Verbesserung gegenüber v1, bei dem die Einbeziehung eines Schritts davon abhängt, ob der zugehörige Vorgang während des Zeitfensters aktiv war, und nicht vom Abschlusszeitpunkt des Schritts selbst. Daher ist bei v1 nicht gewährleistet, dass sich die Summen bei unterschiedlichen Bereichsaufteilungen gleich addieren. Bei v2 ist Folgendes zu beachten: Bei einem Vorgang, dessen Schritte über eine Tagesgrenze hinweg erfolgen, erscheinen diese Schritte in zwei verschiedenen Tagesberichten – jeweils in dem Bericht für den entsprechenden Tag –, statt gemeinsam in einem der beiden Berichte.

​
Die Datumsfilterung basiert auf completedUtc

Im v2-Endpoint filtern sowohl startDate als auch endDate anhand des jeweiligen CompletedUtc-Zeitstempels eines Schritts, nicht anhand einer Start- oder Endzeit auf Vorgangsebene. Da jeder Schritt eines Vorgangs (z. B. Input, Classification, Extraction, Manuelle Überprüfung, Output) einen eigenen CompletedUtc-Wert hat, können die Schritte eines einzelnen Vorgangs auf verschiedene Daten verteilt sein. Jeder Schritt wird unabhängig bewertet und allein anhand seiner eigenen Abschlusszeit ein- oder ausgeschlossen. Wird ein Vorgangsschritt erneut verarbeitet, korrigiert, erneut der Manuellen Überprüfung unterzogen oder aus einem beliebigen Grund wiederholt, wird sein CompletedUtc auf die neue Abschlusszeit aktualisiert. In v2 wirkt sich dies nur auf die Ergebnisse aus, wenn endDate der Abfrage in der Zukunft liegt, also das Zeitfenster noch offen ist. Sobald endDate einer Abfrage in der Vergangenheit liegt, bleiben deren Ergebnisse unverändert: Bei einer erneuten Verarbeitung erhält ein Schritt den aktuellen Zeitstempel, der definitionsgemäß nach einem bereits geschlossenen Zeitfenster liegt. Daher kann der Schritt nicht nachträglich in diesen Report aufgenommen oder daraus entfernt werden.

​
In v2-Ergebnissen erscheinen nur abgeschlossene Schritte

Ein v2-Export gibt nur abgeschlossene Schritte zurück. Ein Schritt, der sich noch in Bearbeitung befindet, etwa ein Schritt mit dem Status Processing, hat keinen CompletedUtc-Wert und wird daher nicht exportiert. Der Schritt erscheint erst in einem späteren Export, dessen Datumsbereich seinen Abschlusszeitpunkt einschließt. v1 gibt alle Schritte eines Vorgangs zurück, der im betreffenden Zeitraum aktiv war. Ein v1-Bericht kann daher auch Schritte enthalten, die noch in Bearbeitung sind. Prüfen Sie in einem v1-Bericht den Status jedes Schritts, bevor Sie ihn als abgeschlossen betrachten. Häufig sollen die Vorgänge des Vortags ausgewertet werden. Verwenden Sie hierfür v2 und legen Sie für startDate und endDate das UTC-Zeitfenster des Vortags von 00:00:00–23:59:59 fest. Da v2 nach dem jeweiligen CompletedUtc eines Schritts filtert, werden genau die an diesem Tag abgeschlossenen Schritte zurückgegeben. So erhalten Sie übersichtliche und konsistente Tageswerte. Verwenden Sie v1 nicht für diesen Zweck. Da v1 jeden Schritt eines Vorgangs zurückgibt, der während des Zeitfensters aktiv war, wird ein Vorgang mit Schritten, die Wochen vor oder nach Ihrem Zieltage abgeschlossen wurden, dennoch vollständig zurückgegeben. Dadurch fließen nicht zugehörige Schritte in die Zahlen für einen einzelnen Tag ein. Beim v2-Ansatz ist Folgendes zu beachten: Bei einem Vorgang, dessen Schritte sich über Mitternacht erstrecken, werden die Schritte auf zwei tägliche Berichte verteilt, jeweils einen pro Tag, anstatt vollständig in einem der beiden Berichte zu erscheinen. Dies ist zu erwarten; siehe oben „Geltungsbereich des Berichtszeitraums“. Solange endDate auf einen Tag festgelegt ist, der bereits vollständig vergangen ist, ist der Bericht stabil und reproduzierbar: Wird dieselbe Abfrage später erneut ausgeführt, liefert sie dieselben Ergebnisse. Wenn Sie stattdessen einen Bereich abfragen, der den aktuellen, noch nicht abgeschlossenen Tag einschließt, können sich die Ergebnisse zwischen den Ausführungen ändern, wenn weitere Schritte abgeschlossen werden (siehe oben „Die Datumsfilterung basiert auf CompletedUtc“).

​
Migration von v1 auf v2

​
Was ist neu?

In der Anforderung (/api/reporting/v2/exports/transaction-steps):
  • Filter wurden von Abfrageparametern in den Request-Body verschoben (filters-JSON-Objekt).
  • startDate, das innerhalb des filters-Objekts angegeben wird, ist jetzt erforderlich.
  • Neues Feld: sendEmailNotification (true/false) – sendet eine E-Mail an den Benutzer der Berichtsanforderung, sobald der Bericht zum Herunterladen bereitsteht.
In den heruntergeladenen CSV-Dateien des Endergebnisses (/api/reporting/v2/exports/transaction-steps/{{requestId}}/result/{fileIndex}) wurden zwei Spalten hinzugefügt:
  • DocumentsCount: Die Anzahl der verarbeiteten Dokumente in einem Vorgang.
  • PagesCount: Die Anzahl der verarbeiteten Seiten in einem Vorgang.

​
Unterschiede bei der API-Nutzung

v1 verwendet eine einzelne GET-Anfrage mit Abfrageparametern und gibt den Bericht direkt zurück. v2 verschiebt Filter in den Request-Body einer POST-Anfrage und teilt den Prozess anschließend in drei Aufrufe auf: den Bericht anfordern, seinen Status abfragen und die Ergebnisse herunterladen, sobald er bereitsteht. Im Folgenden finden Sie Details zur Funktionsweise des v2-Endpunkts.

​
Herunterladen eines Datenberichts

Nur Benutzer mit den Rollen Tenant Administrator und Processing Supervisor können einen Datenbericht aus dem Warehouse herunterladen. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung.
Sie können Daten aus dem Warehouse in einer CSV-Datei mithilfe der Vantage-API abrufen. Senden Sie dazu eine POST-Anfrage an die folgende Ressource: Ein Request-Body sollte innerhalb eines filters-Objekts die folgenden Eigenschaften enthalten:
  • skillId. Die ID des Skills, dessen Vorgänge heruntergeladen werden sollen. Optional.
  • transactionId. Die ID des Vorgangs, nach dem gefiltert werden soll. Optional.
  • startDate. Der erste Tag des Zeitraums (Beispielformat: 2022-01-07T13:03:38, die Uhrzeit muss in UTC angegeben sein), für den die Vorgänge heruntergeladen werden sollen. Filtert nach dem CompletedUtc-Zeitstempel jedes Schritts. Erforderlich.
  • endDate. Der letzte Tag des Zeitraums (Beispielformat: 2022-09-07T13:03:38, die Uhrzeit muss in UTC angegeben sein), für den die Vorgänge heruntergeladen werden sollen. Filtert nach dem CompletedUtc-Zeitstempel jedes Schritts. Optional.
  • sendEmailNotification. Sendet eine E-Mail an den Benutzer, der die Berichtsanforderung erstellt hat, und informiert ihn darüber, dass der Bericht zum Download bereitsteht. Optional.
Berichtsanforderungen werden asynchron ausgeführt, daher enthält die Antwort eine requestId, mit der Sie den Status der Anforderung prüfen können. Ergebnis:
Um den Status des Berichts zu prüfen, geben Sie die requestId in der GET-Anforderung an: Fragen Sie diesen Endpunkt so lange ab, bis der status Succeeded, Failed oder Cancelled lautet. Der status kann einen der folgenden Werte haben: Vantage verarbeitet pro Mandant jeweils nur eine Exportanfrage. Wenn Sie mehrere Anfragen senden, verbleibt jede im Status New, bis die vorherigen Anfragen abgeschlossen sind. Daher kann es länger dauern, bis sie den Status Processing erreicht. Wenn Sie mehrere Berichte benötigen, senden Sie jede Anfrage erst, nachdem die vorherige abgeschlossen ist. Vantage bricht eine Anfrage ab, wenn sie länger als die folgenden Zeiträume in einem Status verbleibt: Wenn der status Failed oder Cancelled lautet, senden Sie zu einem späteren Zeitpunkt eine neue Anfrage. Die Statusantwort enthält außerdem eine correlationId. Geben Sie diese an, wenn Sie sich wegen einer fehlgeschlagenen oder abgebrochenen Anfrage an den ABBYY Support wenden. Wenn der status Succeeded lautet, gibt totalFileCount die Anzahl der Dateien an, die zum Herunterladen bereitstehen:
Um die resultierenden Berichtsdateien herunterzuladen, senden Sie eine GET-Anfrage an den folgenden Endpunkt. Übergeben Sie dabei erneut die requestId und geben Sie zusätzlich den fileIndex an, also den nullbasierten Index der Datei. Bei "totalFileCount": 3 sind beispielsweise die Dateiindizes 0, 1 und 2 verfügbar. Hier ein Beispiel für eine CSV-Antwort:

​
Antwortstruktur

Jede Zeile in einer CSV-Datei ist ein Vorgang, der für einen Vorgang ausgeführt wurde, z. B. der Import von Dokumenten, die Erkennung oder die manuelle Überprüfung. Für jeden Vorgang im Warehouse werden die Details in Spalten gespeichert: Vantage bewahrt die Ergebnisdateien nach Abschluss der Anfrage 14 Tage lang auf. Danach werden die Dateien und die Anfrage gelöscht, sodass die Anfrage nicht mehr in der Liste der Berichtsanfragen erscheint. Daten, die im CSV-Format abgerufen wurden, können anschließend in jedem BI-Tool weiter analysiert werden.

​
Abrufen einer Liste von Reporting-Anforderungen

Um die Liste der Reporting-Anforderungen abzurufen, die innerhalb eines festgelegten Zeitraums gestellt wurden, senden Sie eine GET-Anfrage an den folgenden Endpunkt, wobei createdFrom und createdTo den Datumsbereich angeben und statusFilter einer der folgenden Werte ist: New,Queued,Processing,Succeeded,Failed oder Cancelled. Dies ist hilfreich, falls Anforderungs-IDs nicht mehr auffindbar sind. Die Antwort enthält ein Array von Reportinganforderungen.