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:

1. Import von Dokumenten
2. Export von Dokumenten
3. Als Transferformat für die Dokumentenrecherche
4. Als Datenaustauschformat innerhalb der CLARC-Verarbeitungsstrecke (Queueverarbeitung über die unterschiedlichste Systeme Dokumentendaten auszutauschen und verarbeiten können)
   
   

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:

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:

1. Index und
2. 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:

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:

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.