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. IDLE (Default) Das Document befindet sich in der Queue und wird nach dem FIFO Prinzip verarbeitet ONHOLD Das Document befindet sich in einem Wartezustand ERROR Bei der Verarbeitung hat es einen Fehler gegeben
Task	Spezifiziert den Tasktypen. Folgende Werte sind möglich: EXPORT (Default) XTRACT 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: 000B32B8h047F7188h 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“ DataType=”b” Confidence=“c“ Zone=”d” Page=”e”> </Field>	Feld im Kontext der Index-Sektion Folgende Attribute können verwendet werden: Name (Name des Feldes) DataType (Name des Datentyps) Confidence (Erkennungswahrscheinlichkeit) (0-100 „%“) Zone (Zonenstring (Twips) in der Form (Left,Top,Width,Height) Page (Seite 0..n) 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: UCS2STR (Unicode String) / Default UCS4STR (Unicode String) DOUBLE (Floatwert mit doppelter Genauigkeit) SINGLE (Floatwert mit einfacher Genauigkeit) CURRENCY (Betragswert) DATE (Datumswert in der Form YYYY-MM-DD) BOOLEAN (True oder False) Floatwerte immer in der technischen Schreibweise angeben (mit einem „.“ als Dezimaltrenner).
<Field ID=“a“ DataType=”b”> </Field>	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> </Table>	Aufbau: <Table> <Header> <Fields> <Field Id=”0”></Field> <Field Id=”1”></Field> … </Fields> </Header> <Rows> <Row> <Col Id=”0”></Col> … </Row> <Row> … </Row> </Rows> </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 Confidence=“a” Zone=”b” Page=”c”>	Der Rowtag entspricht einer Tabellenzeile. Er hat folgende Attribute: Confidence (Erkennungswahrscheinlichkeit) (0-100 „%“) Zone (Zone in Twips in der Form Left,Top,Width,Height) Page (Seite auf der sich die Daten befinden (0..n)
<Col id=”a” Confidence=“b“> </Col>	Der Coltag entspricht einer Tabellenzelle. Er hat folgende Attribute: ID (die ID referenziert auf die ID des Feldes im Headerbereich, der den Spaltentyp beschreibt.) Confidence (Erkennungswahrscheinlichkeit) (0-100 „%“)

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: 340A5CB203A341A787C60F5B65576F28.tif

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

Browser nicht unterstützt