Verwendung
Das CLARC Document XML-Format ist ein einfaches und standardisiertes Dateiformat zum Austausch von Informationen über ein einzelnes Dokument. Es enthält durch die Verwendung von XML Tags alle nötigen Eigenschaften um Dokumente, deren Transport und deren Modifikation detailliert beschreiben zu können.
Um das Format erstellen zu können benötigt man zu aller erst einmal nichts Weiteres wie ein Texteditor und etwas XML-Know-How.
Das CLARC Document XML-Format findet innerhalb der gesamten CLARC Produktfamilie eine breite Verwendung. Es wird z.B. in folgenden Bereichen eingesetzt:
- Import von Dokumenten
- Export von Dokumenten
- Als Transferformat für die Dokumentenrecherche
- Als Datenaustauschformat innerhalb der CLARC-Verarbeitungsstrecke (Queueverarbeitung über die unterschiedlichste Systeme Dokumentendaten auszutauschen und verarbeiten können)
Wichtiger Hinweis
In der Version 5.1 gab es Änderungen in der Formatierung von Float- und Currency-Werten. XML's mit alter Formatierung können jedoch weiterhin im System importiert werden.
Beispiel
Das Beispiel zeigt einen einfachen Aufbau eines Document XML’s, welche ID und Stapel-ID das Dokument hat, in welcher Version es vorliegt, wann das Dokument erstellt wurde, mit welchen Indexfeldern es beschrieben wurde und die Informationen zum angefügten Blob.
Selbstverständlich sind noch wesentlich mehr Beschreibungsmöglichkeiten vorhanden, weshalb wir im nachfolgenden das Dokumentenformat detaillierter beschreiben werden.
<?xml version="1.0" encoding="UTF-8" ?>
<ccDocument Id="EC85A327C37346CBAA7DE07122ABD929" StackId="">
<Options>
<CreationDate>000B33E0h030DB376h</CreationDate>
<ChangeDate>000B33E0h030DB376h</ChangeDate>
</Options>
<Content>
<Index>
<Field Name="PROJEKTNUMMER">{B9B0C374-BD88-4A05-AA40-598A63EF9189}</Field>
<Field Name="DOCSUBJECT">Rechnung Nr. 22321</Field>
<Field Name="EINGANGSDATUM" DataType="DATE">2017-01-30</Field>
<Field Name="BETRAG" DataType="SINGLE">500.00</Field>
<Field Name="EMPFAENGER">Maier</Field>
</Index>
<Blobs>
<Blob>
<Name>ccxctrtoc4_20110208141349747_90.tif</Name>
<MimeType>image/tiff</MimeType>
<Extension>.tif</Extension>
<Size>13728</Size>
<Reference>340A5CB203A341A787C60F5B65576F28</Reference>
</Blob>
</Blobs>
</Content>
</ccDocument>
XSD Schema
Das zugehörige XSD Schema finden Sie zum Download im Navigationsbereich der Seite.
Aufbau
Wie jedes XML-File beginnt auch der Inhalt des clarc XML-Files mit der üblichen XML-Kopfzeile.
<?xml version="<Version>" encoding="<Encodingstyp>" ?>
Jedes Dokument muss mit dieser Zeile beginnen und darf keine führenden anderweitigen Zeichen besitzen. Befinden sich Leerzeichen, Tabs oder ähnliches vor der Zeile, dann kann der Parser die Datei nicht korrekt verarbeiten.
Auch der restliche Aufbau entspricht den Paradigmen des XML-Formats. Das heißt im engeren, dass es valide (well formed) sein muss. Verstöße wie z.B. das Weglassen eines schließenden Tags führen ebenfalls dazu, dass ein derartiges Dokument nicht verarbeitet werden kann.
Wir verzichten im Nachfolgenden darauf den XML-Standard detailliert zu beschreiben und verweisen deshalb auf das im Internet befindliche Material, wie z.B. http://de.wikipedia.org/wiki/Xml
Es scheint uns wichtiger die clarc spezifischen Inhalte des Dokumentenformats näher zu beleuchten.
Als äußere Klammer und zur Identifizierung des Dokuments befindet sich stets der ccDocument-Tag unterhalb der XML-Kopfzeile. Er umschließt das ganze weitere Dokument und hat folgende Attribute:
- Id (Uniqe Identifier der dem Dokument einen eindeutigen Schlüssel zuweist - die Länge ist exakt 32 Stellen, nicht kürzer und nicht länger!)
- StackId (Uniqe Identifier der dem Dokument einen eindeutigen Stapel zuweist - max. 32 Stellen)
- URIDocId (Unique Ressource Identifier Document Id mit dem Aufbau doc://Repository/Id)
- Version (Gibt die ganzzahlige Versionsnummer an)
Innerhalb des öffnenden und schließenden ccDocument-Tags wird der weitere Verlauf in zwei wesentliche Sektionen
aufgesplittet:
- Der Sektion Options und
- Der Sektion Content
Jede Sektion sollte nur einmalig vorkommen. Wird eine Sektion mehrfach verwendet (Options[1..n]), dann wird je nach Parser ausschließlich die erste Sektion eingelesen. Die anderen werden ignoriert.
Die gezeigte Reihenfolge der Sektionen wird von uns zwar stets eingehalten, aber auch hier ist der Ersteller frei und kann bei Bedarf die Reihenfolge verändern. Derartige Veränderungen führen bei uns grundsätzlich nicht dazu, dass das Dokument nicht mehr verarbeitet werden kann.
Options
Unter Options werden systemtechnische Informationen aufgelistet. Sie werden primär dazu genutzt, um die Dokumentenverarbeitungsstrecke mit all den Werten zu versorgen die notwendig sind, um das Dokument verarbeiten zu können. Sie haben primär nichts mit dem Inhalt des Dokuments zu tun, sondern mit dessen Verarbeitung und Speicherung.
Die nachfolgende Grafik zeigt die „Options“-Sektion. Diese ist im Beispiel voll ausklassifiziert und beinhaltet alle möglichen Beschreibungstags.
<Options> <State>ONHOLD</State> <Task>EXPORT</Task> <CreationDate>000B33E0h030DB376h</CreationDate> <ChangeDate>000B33E0h030DB376h</ChangeDate> <RetryDate>000B33DFh030DB376h</RetryDate> <Language /> <CheckSum>0030DB376000B33Djjlk030DB376</CheckSum> <Priority>0</Priority> <UserName>dennis</UserName> <Client>CTONB018</Client> <Application>clarc Xtract</Application> <Origin>/CCXTRACT/Example/Default</Origin> <Project>/Test</Project> <Destination /> <ExportTitle /> <Exportservice>/EASY SID Test</Exportservice> <EngineBuffer /> <ScriptBuffer /> <ConvertScheme /> <ScriptScheme /> <PostScriptScheme /> <ExportScheme /> </Options>
Bevor wir uns die Tags und ihre Funktionalität näher anschauen, erörtern wir noch mal kurz zum besseren Verständnis das Beispiel:
Sie finden darin Informationen über den Ursprung des Dokuments (Client, UserName und Application), wo es hin soll und was damit gemacht werden soll (ConvertScheme, ScriptScheme, PostScriptScheme, ExportScheme…). Die Reihenfolge hat keine Bedeutung und es gibt auch keine Pflichtfelder. Fehlen dem System benötigte Informationen, so werden automatisch Defaultwerte verwendet.
Folgende Tags können in der Sektion verwendet werden:
| Tag | Beschreibung |
|---|---|
| State | Der Stateblock beinhaltet den aktuellen Status innerhalb der Verarbeitungsstrecke. Folgende Werte sind möglich.
|
| Task | Spezifiziert den Tasktypen. Folgende Werte sind möglich:
Export (Das Dokument wird zur Verarbeitung an den WARP daemon übergeben bzw. dieser übernimmt die weitere Verarbeitung der angegebenen Prozessstrecke). Xtract (Wird verwendet um das Dokument dem Xtract-Server zur Datenextraktion zu übergeben.) |
| CreationDate | Spezifiziert das Erstellungsdatum. Das Datum wird in einem Timestamp Format spezifischem Format beschreiben. Es stellt das Erstellungsdatum in den Bezug zum 1.1.0001 und hat folgenden Aufbau: Beispiel: Der erste Teil ist das Datum: 000B32B8h Der zweite Teil ist die Uhrzeit: 047F7188h. Das Zeichen "h" kennzeichnet den Ende des Werts und ist kein Bestandteil davon. Siehe auch Timestamp Format. Hinweis Das Datum kann akternativ auch in der ISO schreibweise yyyy-mm-dd hh:nn:ss angegeben werden. |
| ChangeDate | Spezifiziert das letzte Änderungsdatum. Siehe CreationDate. |
| RetryDate | Spezifiziert den Zeitpunkt des frühesten nächsten Verarbeitungsschrittes. Siehe Timestamp Format. |
| Language | Gibt die Sprache an, in der das Dokument vorliegt. Wird das Feld nicht gefüllt, kann das System selbständig die Sprache ermitteln. Als Format ist der „2 Letter Code nach ISO 639-1“ zu verwenden (DE, EN, FR, etc.). |
| CheckSum | Das Feld enthält eine Prüfsumme. Sie wird zur Validierung und Dublettenprüfung herangezogen. Interne Vergabe. |
| Priority | Das Feld beinhaltet einen Ganzzahlenwert zwischen 0-9. Der Wert gibt die Priorität der Verarbeitung an. Umso höher der Wert umso schneller wird das Dokument verarbeitet, wobei bei gleicher Priorität das Eingangsdatum sticht (Priorisiertes First in First out Verfahren). |
| UserName | Benutzernamen der Person welche das Dokument in die Verarbeitungsstrecke überführt hat. |
| Client | Clientsystem, von dem aus das Dokument an die Verarbeitungsstrecke überführt wurde. Es handelt sich dabei um den Computernamen. |
| Application | Das Feld beinhaltet den Namen der Applikation, die das Dokument an die Verarbeitungsstrecke weitergeleitet hat. |
| Origin | Detaillierte Herkunftsinformation. Zusätzlich zur Applikation wird hier auch die entsprechende Unteranwendung oder Projekt, Postfach etc. mit übergeben. |
| Project | Das Feld beinhaltet die Projekt-ID und identifiziert dabei das Projekt auf dem Zielsystems in das das Dokument überführt werden soll. Z.B. das Xtract Projekt. |
| Destination | Die Destination-ID gibt den Identifier des Zielsystems an. Das kann zum Beispiel die Repository-ID innerhalb eines Contentservers sein. |
| ExportTitle | Das Feld beschreibt den Exporttitel und wird je nach Exportservice zur weiteren Verarbeitung herangezogen. |
| Exportservice | Das Feld spezifiziert den Exportservice und somit letztendlich die DLLs die zum Export des Dokuments verwendet werden sollen. Ein entsprechender Exportservice muss im C4 hinterlegt sein, ansonsten kann die Queue das Dokument nicht an das Zielsystem weiterleiten. |
| EngineBuffer | Informationsbereich über den Verarbeitungsschritte (hier Exportservices) Daten austauschen können. |
| ScriptBuffer | Informationsbereich über den die Skripte (Delphi-Skript) Daten an nachfolgende Schritte weiterleiten können. |
| ConvertScheme | Das Feld referenziert auf ein Conversion-Scheme im C4, das dazu verwendet wird, um das Dokument in ein anderes Format überführen zu können. Beispiel: TifToPDF |
| ScriptScheme | Skriptschema das im C4 hinterlegt ist und das über einen Programminterpreter ausgeführt werden kann. |
| PostScriptScheme | Skriptschema das im C4 hinterlegt ist und über eine Programmiersprache Aktionen ausführen kann. Das Skriptschema wird nach der eigentlichen Dokumentenverarbeitung gestartet. |
| ExportScheme | Das Feld spezifiziert das zu verwendete Exportschema, welches den Exportdienst beschreibt und konfiguriert. Exportschemas müssen auf dem C4-Server hinterlegt sein. |
| Subject | Der Betreff des Dokuments. Wird ggf. automatisch aufgebaut. |
| Messages | Nachrichten und Hinweise zum Dokument. |
Content
Der Contentbereich beinhaltet alle Informationen über das Dokument selbst. Das sind zum einen Metabeschreibungsfelder und zum anderen das eigentliche Dokument, dass in Form eines Blobs (Binary Large Objects) enthalten sein kann. Somit wird die Content-Sektion wiederum in die Sektionen:
- Index und
- Blobs
aufgeteilt. Jeder Bereich sollte nur einmal vorkommen, wobei ein mehrmaliges Vorkommen genau so wenig zum Fehlerfall führt wie die Vertauschung der Reihenfolge.
Index
Die Index Sektion beinhaltet alle Metabeschreibungsfelder (Indexfelder). Diese Informationen werden in Form von Feldlisten (Fieldscheme) auf dem C4-Server spezifiziert und bieten dem Anwender die Möglichkeit einem Dokument zusätzliche Informationen zu hinterlegen.
Die Befüllung dieser Informationen kann üblicherweise durch die Datenextraktion maschinengestützt, durch das händische Befüllen durch einen Anwender oder durch den Abgleich mit einem Drittsystem erfolgen.
Das folgende Beispiel zeigt den Aufbau eines XML‘s:
<Content>
<Index>
<Field Name="PROJEKTNUMMER" DataType="UCS2STR">{B9B0C374-BD88-4A05-AA40-598A63EF9189}</Field>
<Field Name="DOCSUBJECT" DataType="UCS2STR" Confidence="98">Rechnung Nr. 22321</Field>
<Field Name="DOCTYPE" DataType="UCS2STR"> AngebotsDocumente.Rechnung</Field>
<Table>
<Header>
<Fields>
<Field Id="0" DataType="UCS2STR">ItemNumber</Field>
<Field Id="1" DataType="CURRENCY">ItemAmount</Field>
<Field Id="2" DataType="UCS2STR">OrderNumber</Field>
</Fields>
</Header>
<Rows>
<Row>
<Col Id="0" Confidence="100">10</Col>
<Col Id="1" Confidence="97">200.00</Col>
<Col Id="2" Confidence="100">552562</Col>
</Row>
</Rows>
</Table>
</Index>
<Blobs>
<Blob>
<Name>ccxctrtoc4_20110208141349747_90.tif</Name>
<MimeType>image/tiff</MimeType>
<Extension>.tif</Extension>
<Size>13728</Size>
<Data>
<![CDATA[
SUkqAAgAAAAPAP4ABAABAAAAAAAAAAABBAABAAAAcAYAAAEBBAABAAAAIgkAAAIBAwABAAAAAQAA
AAAAAgAAADEBAgA3AAAA0gAAAAAAAADIAAAAAQAAAMgAAAABAAAAUGl4ZWwgVHJhbnNsYXRpb25z
...
]]>
</Data>
</Blob>
</Blobs>
</Content>
Beschreibung:
| Parameter | Beschreibung |
|---|---|
<Field Name=“a“ | Feld im Kontext der Index-Sektion Folgende Attribute können verwendet werden:
Lediglich die Angabe des Feldnamens ist obligatorisch. Alle weiteren Attribute sind optional. Confidence kann z.B. dazu benutzt werden, um zu kennzeichnen wie hoch die Wahrscheinlichkeit ist, dass eine automatische Texterkennung (OCR) den Wert richtig erkannt hat. Im Zusammenhang der automatischen Erkennung können auch die Attribute Zone und Page belegt werden. DataType wird optional verwendet und gibt an, wie der Feldinhalt zu interpretieren ist. Im Standard ist DataType immer „UCS2STR“ – ein Unicode String. Folgende Werte sind möglich:
BOOLEAN (True oder False) |
<Field ID=“a“ | Feld im Kontext der Table-Sektion Dieser Fieldtag wird dazu verwendet, um eine Tabellenspalte zu beschreiben. Dabei wird der Spaltennamen dem Attribut ID gegenübergestellt. Die Tabellenzellenwerte referenzieren danach Ihrerseits immer auf die ID und somit auf den Feldtyp. Der Datentyp wird analog zum Indexfeld definert (s.o.) und gilt für alle Zellen der Spalte. |
<Table> | Aufbau: <Table> Table beinhaltet eine Header-Sektion die wiederum eine Fields-Sektion beinhaltet. Die Fields-Sektion beinhaltet einen oder mehrere Fieldtag(s) (im Kontext der Fields-Sektion). Neben der Fields-Sektion gibt es noch die Rows-Sektion die die Tabellenzeilen symbolisieren. Jede Rows-Sektion hat eine oder mehrere Row-Section(s). Eine RowSection hat einen oder mehrere Col-Tag(s), wobei der Col-Tag einer Tabellenzelle entspricht. |
<Row | Der Rowtag entspricht einer Tabellenzeile. Er hat folgende Attribute:
|
<Col id=”a” | Der Coltag entspricht einer Tabellenzelle. Er hat folgende Attribute:
|
Blobs
Der Blobbereich beschreibt eine oder mehrere Seiten des Dokuments in Form von BASE64 verschlüsselten Binärabzügen oder Verlinkungen auf das Dateisystem. Innerhalb des <Blobs> Bereichs können beliebig viele einzelne <Blob> Sektionen verwaltet werden. Die max. Menge ergibt sich aus der Limitierung des entsprechenden XML DOM Parsers.
<Content>
<Index>
<Field Name="PROJEKTNUMMER">{B9B0C374-BD88-4A05-AA40-598A63EF9189}</Field>
<Field Name="DOCSUBJECT">Rechnung Nr. 22321</Field>
<Field Name="DOCTYPE"> AngebotsDocumente.Rechnung</Field>
</Index>
<Blobs>
<Blob>
<Name>Inplace-Beispiel</Name>
<MimeType>image/tiff</MimeType>
<Extension>.tif</Extension>
<Size>13728</Size>
<Data>
<![CDATA[
SUkqAAgAAAAPAP4ABAABAAAAAAAAAAABBAABAAAAcAYAAAEBBAABAAAAIgkAAAIBAwABAAAAAQAA
AAAAAgAAADEBAgA3AAAA0gAAAAAAAADIAAAAAQAAAMgAAAABAAAAUGl4ZWwgVHJhbnNsYXRpb25z
...
]]>
</Data>
</Blob>
<Blob>
<Name>Referenz-Beispiel</Name>
<MimeType>image/tiff</MimeType>
<Extension>.tif</Extension>
<Size>34341</Size>
<Reference>340A5CB203A341A787C60F5B65576F28</Reference>
</Blob>
<Blob>
<Name>Weiteres Referenz-Beispiel</Name>
<MimeType>application/pdf</MimeType>
<Extension>.pdf</Extension>
<Size>2328372</Size>
<Reference>MyReferenceId_0000000001</Reference>
</Blob>
...
</Blobs>
</Content>
Eine Blobsektion hält folgende Informationen:
| Tag | Beschreibung |
|---|---|
| Name | Der Tag findet Verwendung um den Namen des Dokuments zu beschreiben. |
| MimeType | Der Tag spezifiziert den Mimetype des Blobs. Dabei ist die HTML-Mimetype-Spezifikation bezüglich des Formats zu beachten. Z.B. image/tiff |
| Extension | Der Extentions-Tag enthält die Fileendung wie z.B. .pdf. Dabei ist der führende Punkt noch mit an zugegeben. |
| Size | Unter Size ist die Dateigröße in Bytes anzugeben. |
| DocType | Dokumentart - frei definierbar. |
| Data | Im Datablock wird die zu speichernde Datei im Binärformat abgelegt. Innerhalb des Datablocks ist es zwingend notwendig, den Inhalt mit einem CDATA Block zu umschließen. Gerade in Binärdateien finden unterschiedlichste Sonderzeichen Verwendung, die ohne CDATA bei der Verarbeitung zu einem Fehlerfall führen würden. |
| Reference | Alternativ zur integrierten Datenhaltung der Blobs kann eine Referenz auf eine externe Datei angegeben werden. Die Datei muss sich dabei im gleichen Verzeichnis wie das .xml befinden. Der Name der Datei baut sich aus <Reference> und <Extension> auf. Hier ein Beispiel: |
Validierung
Um die Gültigkeit von der jeweiligen XML zu überprüfen kann mittels des angefügten XSD Schemas und einem XML Editor die eigene XML gegen die Spezifikation geprüft werden.
Wir empfehlen die Verwendung von folgendem Link : https://github.com/Microsoft/XmlNotepad/wiki
Über den XML-Editor können die XML-Dokumente einfach bearbeitet und validiert werden. Über den Reiter View > Schemas kann das XSD Schema geladen werden. Nach einen Klick auf “OK“ wird die geöffnete XML gegen das Schema geprüft.
Im Fußbereich des Editors werden jetzt in der „Error List“ eventuelle Unstimmigkeiten angezeigt, sofern welche auftreten.
XSD Schema