REST API

Mantiseinträge

 3212

Systemtyp

 69 

Eintrittsinvarianz

JA

Beschreibung

OJOHZDORestApi

Wurde als Pilotprojekt für die Parashift API entwickelt und wird aktuell nur im Zusammenhang mit AI Feldextraktion von Dokumenten verwendet.

Die verfügbaren API's werden nun auf Micorsoft Azure weiterentwickelt.

Der Arbeitsschritt stellt eine Verbindung zu einer WEB-API her, und führt von der API zur verfügung gestellte Befehle aus.

Damit können z.B.:

• Dateien hochgeladen werden
• Metadaten übermittelt (aktuell nur abholung) werden
• Externe Prozesse verfolgt oder gesteuert werden

Weitere Zugehörige Arbeitsschritte

Quittierung - Warten Schritt, welcher auf eine Bestätigung der Gegenstelle wartet. z.B. wenn alle Metadaten bereistehen.

Konfiguration

Das Konfigurationsfenster besteht jeweils aus zwei Teilen:

• Auswahl und Konfiguration des API Anbieter
• Auswahl und Konfiguration eines verfügbaren API Befehls

Die Konfiguration ist je nach Anbieter unterschiedlich. In der Regel verlangt jeder Anbieter eine Authentifizierung und Authorisierung. Dies wird meistens in Form einers API-Keys (Token) gehandhabt.

Ein Wechsel zwischen Anbieter und/oder Befehlen hat die Löschung der aktuellen Konfiguration zur Folge und muss deshalb zusätzlich bestätigt werden.

Der Schritt hat 3 mögliche Ausgänge. Wobei der dritte Ausgang nicht für alle Befehle zur verfügung steht und je nach Befehl ggf. unterschiedlich ausgelöst wird.

Aktuelle Befehle mit drittem Ausgang:

Azure Feldextraktion V2

Verfügbare Anbieter

Azure AI Dokumente Erkennung

Dies ist eine Cognitive Service Anwendung von Microsoft Azure zur AI unterstützen Erkennung von Dokumenteninhalten.
Hilfe zur Konfiguration von Azure siehe: Anleitung für Azure Document Intelligence

Der Job hat z.Z einen Befehl. Mit diesem werden in einem einzigen Schritt Dokumente zur Feldextraktion zu Azure geladen, welche in Echtzeit synchron verarbeitet werden. Sobald die Auswertung abgeschlossen ist, werden die ermittelten Informationen zurück gesendet und vom Job ausgewertet und in die Metadaten des Objektes übertragen. Die Verarbeitung eines Dokumentes dauert in der Regel zwischen 10-15 Sekunden.

API Konfiguration

Die API verlangt den Endpunkt URL (API Pfad) und den API Key der zugehörigen Document Intelligence Resource in Azure.

API Befehle

Übergreifende Einstellungen

Die AI Model ID kann entweder als einen fixen Wert mit Anführungszeichen ( 'meinModel' ) oder mit Platzhalter und dem Verweis auf ein Metadatumsname des Objektes ( [metadatumMitModelID] ) angegeben werden. Wenn alle Objekte zum gleichen Model gehen, dann ist ein fixer Wert der richtige Weg. Wenn die Objekte unterschiedliche Dokumententypen enthalten, dann müssen diese zuvor klassifiziert bzw. segementiert worden sein. Der Dokumententyp sollte dabei gleich in einem entsprechenden Metadatum gespeichert werden. Idealerweise sind die Bezeichnung des Dokumententyps und der dazu zugehörigen AI ModelID identisch. Somit kann über dieses Metadatum dann gleich das richtige Model ausgewählt werden.

Der Dateityp ist entsprechend dem Dateiart der Dokumente einstellen. Es muss zwingend ein Typ angegeben werden.

Dateien hochladen, Feldrückgaben in Metadaten speichern (V1) & (V2)

Version V1 - Speichert nur die Felder und überprüft die Konfidenz nur hinsichtlich der Zuversicht, dass das gesuchte Feld überhaupt gefunden wurde. Die Konfidenz bezieht sich nicht auf den OCR Textinhalt! Diese Version erlaubt auch keinen nachfolgenden, Feldbezugsintegrierten Qualitätssicherungschritt, bei welchem die Felder durch Menschenhand überprüft und validiert werden.

Version V2 - Diese Version bietet eine genauere Konfidenzauswertung, welche auch die OCR Erkennung berücksichtigt. Die detaillierte Konfidenzvalidierung kann in einem Metadatum gespeichert werden, welches in einem späteren Kontrollieren Arbeitsschritt zur visualisierung der ermittelten Felder angewendet werden kann. Es wird zudem die Angabe von Seitenzahlen in PDF Dokumenten unterstützt

Technische Details zur JSON Rückgabe der ermittelten Felder

In den Rückgabewerten gibt es zwei Elemente, welche den erkannten Text aus einem Feld wiedergeben: “content” ist der exakte erkannte Text aus dem Dokument (inklusive eventueller Satzzeichen etc.), während “valueString” der von Azure Document Intelligence bereits interpretierte bzw. normalisierte Wert ist. Aktuell übertragen wir die Daten aus dem Feld "valueString".

"value": "Ackermannstr",
"content": "Ackermannstr."

Lädt ein Dokument vom Typ PDF, TIFF, JPG oder PNG zu einem AI Model eines Endpunktes von Azure Cognitive Services hoch. Es werden mehrseitige PDF und TIFF Dateien unterstützt.
Für mehrseitige Dokumente wird die Erstellung von PDFs empfohlen.
Die Dateien sollten dabei, unter der Berücksichtigung der Qualität, immer möglichst klein gehalten werden. Da von den Dokumenten auf Azure zuerst ein OCR gemacht werden muss, ist die OCR Erkennung der Massstab für die benötigte Qualität.

Maximale Dateigrösse: 50 MB
Maximale Auflösung: 10'000 x 10'000 Pixel

Damit die Dokumente zum zugehörigen trainierten AI Model gesendet werden können, ist eine Modelbezeichnung (Model ID) anzugeben. Anleitung zum Trainieren eines Extraktionsmodel

Beim Training des Models werden den Feldern oder den Tabellen Namen vergeben. Damit die erkannten Feldinhalte den Metadaten zugewiesen werden können, ist in der Befehlskonfiguration eine Zuordnung (mapping) zu machen.

Pro Objekt kann nur eine Datei hochgeladen werden! Wenn sich mehrere Dateien in dem Ordner befinden, so wird die erste der natürlichen Sortierreihenfolge genommen.

(Nur in V1) Die Einstellung einer globalen Konfidenz über das aktivieren der Checkbox bewirkt, dass der daneben eingestellte Wert als Schwellenwert für alle Felder verwendet wird. Fällt ein Feld unter diesen Wert, dann geht das Objekt zum Fehler Ausgang und muss geprüft werden. Wenn keine globale Konfidenz ausgewählt wird, dann wird die Konfidenzeinstellung für jede einzelne Zuordnung individuell laut der Konfiguration in den Zuorndungstabellen für Felder und Tabellen berücksichtigt.

Soll keine Konfidenzprüfung stattfinden, dann ist der Wert für die globale Konfidenz auf 0.00 zu stellen und das häckchen zu setzen.

Zusätzliche Daten - Für Kontrollschritte oder OCR Text

Normalerweise werden nur die Daten aus den ermittelten Feldern gespeichert. Es findet sich hier eine Option, um die vollständigen Extraktionsdaten welche im JSON Format zurückkommen, zu sichern. Dazu muss dazu ein eigenes Attribut angelegt werden. Diese Daten enthalten unter anderem den OCR der Datei, sowie Positionskoordinaten der einzelnen Felder. Diese werden ggf. benötigt, um in einem späteren Kontrollschritt die Textstellen automatisch farblich zu markieren. Werden nur die Daten für die Kontrolle benötigt, dann empfiehlt sich die zusätzliche Option, ausschliesslich die Feldextraktionsdaten zu sichern. Dies kostet weniger Speicherplatz und Zeit.

Version V1

Zuordnung von Feldern V1

Der Befehl kann zwei unterschiedlliche Feldtypen verarbeiten; Einfache Felder, und/oder Tabellen.

Für jedes Metadatum ist eine Zeile mit der Zuordnung zum entsprechenden Feld des AI Models in die Tabelle einzufügen. Die grüne Taste + fügt eine Zeile hinzu. Die rote Taste x löscht die ausgewählte Zeile.

Wenn ein Metadatum nicht fehlen darf, also ein Pflichtfeld ist, wähle das Häckchen bei 'Ist Pflicht' an.

Für jedes Feld kann eine eigene Kofidenzeinstellung eingetragen werden. Diese kommen nur zur Geltung, wenn die globale Konfidenz deaktiviert wurde!

Über die Taste 'Globale Konfidenz vererben' kann der Wert aus dem globalen Konfidenz Feld auf alle Zeilen der Tabelle übertragen werden. Sinnvoll für den Fall, dass nur wenige Felder eine Abweichende Einstellung erhalten sollen, oder wenn die Werte rasch alle korrigiert werden müssen.

Zuordnung von Tabellen V1

Grundsätzlich die gleiche Funktionalität wie für Felder. Hier wird jedoch der gesammte Inhalte eine Tabelle in ein Metadatumsfeld übertragen.

Die Formatierung als Tabelle wird dabei folgendermassen beibehalten:

 'Wert' TRENNZEICHEN 'Wert' TRENNZEICHEN 'Wert' ZEILENUMBRUCH
 'Wert' TRENNZEICHEN 'Wert' TRENNZEICHEN 'Wert' ZEILENUMBRUCH
 'Wert' TRENNZEICHEN 'Wert' TRENNZEICHEN 'Wert' ZEILENUMBRUCH

Wähle das entsprechend gewünschte Trennzeichen aus der Dropdownliste. Standardtrennzeichen ist der Tabulator (TAB).

Version V2

Zuordnung von Feldern V2

Die Zuordnung ist analog wie bei V1 gestaltet, es werden jedoch zwei weitere Konfidenzwerte verlangt. Es gibt keine globale Konfidenzeinstellung.

Die "Feldkonfidenz gefunden" bezieht sich auf die in der Konfiguration angegebene Sicherheit, dass das Feld tatsächlich gefunden wurde. Unabhängig von dessen Inhalt, sondern nur, dass das antrainierte Feld ermittelt werden konnte. Dies ist die Konfidenz, welche in Version V1 des Befehls als einzige zur Verfügung steht. Für diesen Fall wurde dem Feld auch zwingend ein Text zugeordnet.

Die "Feldkonfidenz nnicht gefunden" bezieht sich auf den Fall, dass das Feld mit der angegebenen Sicherheit nicht gefunden wurde. Für diesen Fall gibt es folglich auch sicher keinen Text zu dem Feld.

Die "OCR Konfidenz" bezieht sich auf die angegebene Texterkennungssicherheit und kommt nur zum tragen, wenn das Feld ermittelt werden konnte und die Feldkonfidenz überhalb der eingestellten "Feldkonfidenz gefunden" liegt.

Validierungsdaten für späteren Kontrollschritt sichern Falls darauf ein entsprechender manueller Kontrollschritt folgt, müssen die Validierungsdaten in einem dafür erstellen Metadatum gespeichert werden. Ansonsten kann nicht automatisch visualisiert werden, welche Felder die Validierung nicht bestanden haben. Dazu ist das Feld "Attribut für die Konfidenz Validierungsdaten" mit dem Namen des Attribut zu füllen. Als Standardwert ist dort bereits "konfval" eingetragen. Der Name kann beim erstellen des Attribut für die Objekte übernommen werden, oder falls ein anderer Name gewählt wurde, ist dieser hier entsprechend zu überschreiben.

Zum Verständniss der Validierungskonfiguration

• Objekte welche "Dunkel" durchlaufen, gehen zum Ausgang 1
• Objekte welche NUR OCR Konfidenzschwellwerte verletzen, gehen zum Ausgang 2
• Objekte welche Feldermittlungsschwellwerte (Feld nicht gefunden!) verletzen, gehen zum Ausgang 3

Sollen die Objekte mit Schwellwertverletzungen egal welcher Art zum selben Folgeschritt gelangen, dann ist Ausgang 2 und Ausgang 3 mit dem nächsten Schritt zu verbinden.

Bsp.:

Ein gefundenes Feld muss mit hoher Sicherheit dem Trainierten Feld entsprechen, der erkannte Text in dem Feld soll ebenfalls mit hoher Sicherheit erkannt worden sein. Es ist ein Pflichtfeld. Es wird eine hohe "Feldkonfidenz gefunden" und eine hohe "OCR Konfidenz" eingestellt. Wenn das Feld nicht gefunden wurde, muss dies mit hoher Sicherheit erkannt worden sein. Es wird eine hohe "Feldkonfidenz nicht gefunden" eingestellt.

Wird das Feld nicht gefunden, dann wird über die Konfidenz geprüft, wie sicher es ist, dass es nicht gefunden wurde. Ist die Bewertung zu unsicher, dann geht das Dokument zur Kontrolle. Ist die Bewertung sicher, dann entscheidet die Pflichtfeldeinstellung, ob das Dokument geprüft werden muss. Falls es kein Pflichtfeld ist geht das Dokument dunkel weiter.

Wird das Feld gefunden, dann wird über die Konfidenz geprüft, wie sicher es ist, dass es gefunden wurde. Ist die Bewertung zu unsicher, dann geht das Dokument zur Kontrolle. Ist die Bewertung sicher, dann entscheidet die OCR Konfidenz Bewertung, ob das Dokument geprüft werden muss.

Dokumente klassifizieren

Dieser Schritt ermöglicht die Separierung von Dokumenten unterschiedlichen Typs. Dazu muss ein entsprechendes Custom Classification Model in Azure trainiert worden sein, auf welches z.B. über ein Metadatum dass den Modelnamen enthält, zugegriffen wird.

Die Schnittstelle dieses Befehls wurde vollständig auf die REST API (https) umgestellt. Sie verlangt neu die Angabe der für das Model zur Anwendung kommenden API Version. Diese findet sich unter den Einstellungen auf der Trainingsplattform der DocumentIntelligence.

Der ermittelte Typ wird im entsprechend eingerichteten Metadatum gespeichert, dessen Name in des Feld "Attribut für Dok. Typ" eingetragen wird. Als standard steht dort bereits "doktyp". Wenn ein Metadatum mit diesem Namen erstellt wird, dann ist die Konfiguration gleich korrekt eingerichtet.

Die Rückgabe der Analyse kann hier ebenfalls in einem Metdatum gespeichert werden. Hier wird "jsonvalue" als Name vorgeschlagen und ist entsprechend wie beim Dok. Typ Attribut zu erstellen oder durch ein eigens erstelltes Metadatum zu ersetzen.

Über die Konfidenz wird wiederum der Schwellwert für die sichere Bestimmung des Typs eingestellt. Liegt der erhaltene Wert darunter, geht das Objekt zum zweiten Ausgang (z.B. zur Kontrolle).

Parashift

API Konfiguration

Die API verlangt aktuell nur nach einem API Key. Dieser ist in das entsprechende Feld einzugeben und muss beim API Provider erstellt werden.

API Befehle

Dokumente upload

Lädt Dateien zu einem Parashift Workflow hoch. Bei PDF Dateien können zusätzlich die zu berücksichtigenden Seitenzahlen angegeben werden.

Felder:

Interne ID - Helper Objektidentifikation, Standard = DOSEQ. Aktuell möglich sind DOSEQ, DOSIGNATUR.

Objektname - Der Name für das Objekt, wird auf der Parashift Webseite entsprechend zur identifikation verwendet. Verwendet Platzhalter, erlaub sind [DOSEQ], [DOSIGNATUR] und [FILENAME]

Klassifizierungsscope - Weist ein Objekt direkt einer Klassifizierung zu. Überspringt die Erkennung des Dokumentetyps auf der Gegenseite. Ist der Scope bekannt, sollte das Feld entsprechend gefüllt werden. Erlaubt die Angabe mehrerer möglicher Scopes als Kommagetrennte Werte (e.g.: Einwohnerkarten, Haustierkarten, XYKarten)

Upload Konfiguration - Ist auf der Gegenstelle im Web-UI für den entsprechenden Workflow / Projekte zu Konfigurieren. Standard=client

Validierung erforderlich - Standard = nein. Gibt an, ob Objekte bei der Verarbeitung zusätzlich manuell validiert werden müssen.

Nicht für Training verwenden - Standard = ja. Gibt an, ob das Objekt für das Training des Erkennungsalgorhytmus verwendet werden soll.

Seitennummer(n) - Kommagetrennte Liste mit den zu berücksichtigenden Seitennummern. Bei PDF werden nur die angegebene Seitennummern aus einem Dokument übermittelt. Bei Bildern entsprechend nur die der Sortierreihenfolge nach Dateiname enstsprechenden Dateien. Standard = leer (alle Seiten senden)

Dateityp - Welche Art von Dateien werden beim Upload berücksichtigt?

Metadaten abholen

Holt die bei Parashift ermittelten Metadaten ab und speichert diese in den zugehörigen Attributen.

Varianten:

'Standard: Provider ID' - Verwendet zum finden des zugehörigen Dokuments die Dokumente ID der Gegenstelle (Feld = DO_ISQ). Diese ID ist eindeutig, es können somit mehrfache Objekte mit der gleichen Helper ID (DO_SEQ) existieren.

'Helper ID' - Verwendet zum finden des zugehörigen Dokuments die Objekt ID aus dem Helper (Feld = DO_SEQ)
WICHTIG: Wenn die DO_SEQ als ID zum ermitteln eines hochgeladenen Objektes verwendet wird, dann muss sichergestellt werden, dass dieses Objekt nicht mehrfach hochgeladen wurde. Bzw. es darf dann bei Parashift nicht mehr als ein Objekt gleichzeitig mit der selben Helper ID existieren. Alle duplikate müssen auf der Parashift Plattform zuerst gelöscht worden sein.

Konfiguration:

Für jedes zu importierende Metadatum muss eine Zeile in der Tabelle erstellt werden, welches den Attributsnamen im Helper mit dem Attributsnamen der Gegenstelle mapped. Gross-Kleinschreibung beachten!

Wird die Option "Ist Pflicht" ausgewählt, dann darf das empfangene Attribut nicht leer sein. Die Objekte gehen sonst in Fehlerstatus.