Erste Schritte

Auf dieser Seite werden die ersten Schritte zu einem erfolgreichen Import erklärt.

Grundeinrichtung

Die Installation und Grundeinrichtung wird unter Installation beschrieben. Sie ist die Voraussetzung um den ersten Import erfolgreich einzurichten. Probleme bei der Installation und Grundkonfiguration können in der Regel schnell über den FAQ Bereich gelöst werden.

Erster Import

Im Folgenden wird die Konfiguration des ersten Imports nach CORSA erklärt.

Zuerst ist es notwendig die Rahmenbedingungen des Impotkanals in der system.ini festzulegen. Anschließend wird die Datentransformation und somit die gewünschte Ablage in CORSA über eine mapping.ini definiert.

Ausgangssituation ist ein Datenpaar bestehend aus einer PDF Datei und einer zugehörigen Indexdatei als CSV. Beide Dateien haben den selben Dateinamen und werden in D:\stratoz\data\records2corsa bereitgestellt.

Beispiel:

D:\stratoz\data\records2corsa\example.pdf
D:\stratoz\data\records2corsa\example.csv

Die CSV Datei ist wie folgt aufgebaut:

date;organisation;iban;invoiceno;invoicedate
20.09.2016;FernUniversität in Hagen;DE13450600095015050901;199042326209;19.09.2016

Importkanal

Ein Importkanal wird eingerichtet, indem eine neue IMPORT Sektion in der system.ini erstellt und konfiguriert wird.

Beispiel:

[IMPORT01]
Internal_Key        = j1PfxNPnfzs4SKR7YMXvIvYXclKyPZ5QfUHOowB/c4CTXHNdpIvDQedmrXmMCKsjJDHofgAZtrTuBuwq73prJA
Name                = Records2Corsa Import
Priority            = 1
SourceDir           = ../../../data/records2corsa
idxFileExtension    = csv
ColSep              = format %c 44
Function            = ::MakeSubDir::MakeSubDir $counter -seconds 10
BackupDir           = E:/backup/records2corsa
BackupSubDirs       = 1
ErrorDir            = ../error
USETIMESTAMP        = 1
RunningTimeWeek     = 02:00:00-22:00:00
RunningTimeSA       = 02:00:00-22:00:00
RunningTimeSU       = 02:00:00-22:00:00
MappingFile         = ./mapping/r2c_mapping.ini
MAPPINGRULE         = expr {$line eq ""}
MAPPINGFILEIF       = ./mapping/empty_mapping.ini
RetryUpload         = 10
CheckVersionNo      = 0

Die Sektion für einen Importkanal trägt immer den Namen IMPORT gefolgt von 2 Zahlen, in diesem Beispiel "IMPORT01" und muss in eckige Klammern gesetzt werden. Für die Lizenzausstellung benötigt die StratOz GmbH den Namen des Importkanals. Der ausgestellte Lizenzkey muss hinter dem Internal_Key gespeichert werden. Der festgelegte Name wird bei dem Versand von Ereignis E-Mails verwendet und dient zur schnellen Übersicht. Prioritäten ermöglichen es bestimmte Daten vorrangig nach Corsa zu importieren. Immer wieder kommt es vor, das bestimmte Dokumente sofort in Corsa verfügbar sein sollen, hingegen z.B. E-Mails zweitrangig abgearbeitet werden. Ein kleiner Priority Wert erhöht die Priorität dieses Importkanals.

Jetzt wird festgelegt wo die zu importierenden Datenpakete liegen. Der Importservice erwartet im Quellordner "SourceDir" immer ein numerischen Unterordner mit einer darin enthaltenen Indexdatei und ggf. weiteren Dateien. Der Pfad kann relativ zum Pfad des Importservice angegeben werden oder absolut. Hierbei ist wichtig ein Backslash "\" durch ein Slash "/" zu ersetzen. Das SourceDir und die Dateiendung der Indexdatei "idxFileExtension" (hier csv) müssen festgelegt. Sobald der Importservice eine csv Datei in einem numerischen Unterordner des Quellverzeichnisses sieht, wird er diesen Ordner verarbeiten. Indexdateien werden immer im UTF-8 Encoding erwartet, sollte dies einmal nicht der Fall sein, so muss dies zwingend über den Parameter Encoding gesetzt werden. Eine Fehlkonfiguration kann zu außergewöhnlichen Verhaltensweisen und schwer nachvollziehbaren Fehlern führen. Standardmäßig sind die Trennzeichen für Datensätze in der Indexdatei für Datensatztrenner auf Zeilenumbruch also "\n", der Wertetrenner auf Pipe also "|" und der Spaltentrenner auf Semikolon also ";" festgelegt. Weichen diese Trennzeichen in den Datensätzen des Quellordners ab, so sind sie korrekt zu definieren. Hier wird das Spaltentrennzeichen auf "," geändert, indem der Wert des UTF-8 Zeichens in Form von "format %c 44" definiert wird.

Es kommt immer wieder vor, dass die Daten für den Importservice nicht direkt in einem numerischen Unterordner vorliegen. Die Funktion "::MakeSubDir::MakeSubDir" kann hier Abhilfe schaffen, wenn die Daten immer in Form einer Indexdatei und gleichnamiger Dokumentendatei im Quellverzeichnis abgelegt werden. Zum Beipiel: scan001.csv und scan001.pdf werden im Quellordner gespeichert, die Funktion "::MakeSubDir::MakeSubDir" wird nun nach den angegebenen Sekunden das Dateipärchen in einen numerischen Unterordner verschieben. Die Daten werden dann normal verarbeitet.

Zur Sicherheit können von allen Daten durch Festlegen eines "BackupDir" Backups erzeugt werden. Bei großen Datenmengen empfiehlt es sich die Daten im Backupverzeichnis in Unterordner zu speichern. Hierzu muss der Parameter "BackupSubDirs" aktiviert, also auf 1 gesetzt werden.

Sollte ein Fehler beim Importieren eines Datensatzes auftreten, so werden die fehlerbehafteten Daten in den definierten "ErrorDir" Ordner verschoben. Wenn nicht sichergestellt werden kann, dass die Dateinamen eindeutig sind, so muss der Parameter "USETIMESTAMP" auf 1 gesetzt werden. Ansonsten besteht die Gefahr von Datenverlust weil Dateien mit gleichem Dateinamen überschrieben werden!

Die Laufzeiten des Importservice können durch setzen von "RunningTimeWeek", "RunningTimeSA" und "RunningTimeSU" eingeschränkt werden. Dies ist hilfreich um konsistente Datensicherung in der Nacht zu erstellen. In diesem Beispiel wird der Importservice keine Importe zwischen 22 Uhr und 2 Uhr durchführen.

Die Konfiguration des Importkanals ist fast abgeschlossen. Jetzt muss nur noch die Datei zur Konfiguration der Datentransformation "MappingFile" festgelegt werden. Auf Grund von häufig existierenden Leerzeilen am Ende der Indexdatei ist es notwendig solche zu identifizieren und auszuschließen. Wird dieser Ausschluss nicht konfiguriert, so werden Fehler auftreten, da leere Werte an Corsa übergeben werden. Durch festlegen der "MAPPINGRULE" wird die Leerzeile mit der darauf folgenden Datentransformationsdatei "MAPPINGFILEIF" verarbeitet. MAPPINGRULE und MAPPINGFILEIF können auch mehrfach untereinander konfiguriert werden. Dies bietet die Möglichkeit individuell auf Inhalte der Indexdatei einzugehen und unterschiedliche Datentransformationen festzulegen.

Zuletzt wird in diesem beispiel noch die Wiederholung des Uploads "RetryUpload" auf 10 Versuche festgelegt. "CheckVersionNo" dient zur Sicherheit, keine Dateiversionen in Corsa zu überschreiben. Dies kann vorkommen wenn mehrere Prozesse Dateien an eine Registrierung in Corsa speichern und zwischen der ermittelten nächsten freien Dateiversion und dem tatsächlichen Upload der Datei ein weiterer Prozess diese Version erstellt hat. Diese Sicherheit wird bei dem Besispiel deaktiviert, da sichergestellt ist, dass kein anderer Prozess diese Datei erstellen kann (Verwendung eines Uniquekeys basierend auf der Datei zur Erstellung der Registrierung in Corsa).

Grundsätzlich sollte immer für jeden Importprozesss ein Uniquekey gefunden werden. Sollte dieser nicht schon in den Indexdaten enthalten sein kann ein SHA256 vom Importservice über die Datei erstellt und für die eindeutige Registrierung verwendet werden. Somit werden Datenduplikate vermieden.

Datentransformation

Nachdem der Importkanal technisch eingerichtet ist, werden im Folgenden die Daten aus der Quelldatei nach Corsa transformiert. Mit der Konfiguration des Datenpaketes wurden bereits die Felder mit deren Werte separiert. Folglich stehen jetzt alle Feldnamen als Variablen für das Mapping zu Verfügung.

Vor dem Mapping müssen einige Informationen klar sein.

1. Ein eindeutiger Schlüssel sollte für jeden Datensatz definiert werden. Bei Personen kann dies beispielsweise die ID des Referenzsystems sein. Bei Dokumenten kann ein Barcode aus dem Scannprozess verwendet werden oder wenn kein eindeutiger Schlüssel vorliegt auch der Hashwert der zugehörigen Datendatei. Bei einem eindeutigen Schlüssel kann die Dokumenttyp-Nummerierung in Corsa automatisch erfolgen weil das Dokument durch ein eindeutiges Zusatzfeld mit dem Schlüssel befüllt und darüber wieder gefunden wird. Es ist auch möglich bei einem neuen Dokumenttyp die Nummerierung auf manuell zu stellen und beispielsweise ein Barcode als Dokument ID zu verwenden.

2. Pflichtfelder sollten aus dem Datenpaket festgelegt werden. Fehlen Informationen so können importierte Daten unbrauchbar werden oder auf Fehler stoßen. Fehlt zum Beispiel die Information für den eindeutigen Schlüssel, so wird der mit Leerwert als eindeutige Identifizierung existierende Datensatz in Corsa überschrieben. Um Datenverlust zu vermeiden, muss eine solche Situation zwingend vermieden werden. Die Funktion Required kann hierbei unterstützen.

3. Strukturierte Ablage von Informationen ist der Mehrwert eines ECM. Aus diesem Grund sollte vorher klar sein, wie Daten in CORSA abgelegt werden damit Benutzer die Informationen schnellstmöglich wieder finden. Hierzu zählen definierte Aktenstrukturen in die Dokumente verknüpft werden und eine einheitliche Verschlagwortung. Ein Vertrag wird beispielsweise automatisch mit einer Organisation und der zugehörigen Organisationsakte "Verträge" verknüpft. Die Verschlagwortung über das Inhaltsfeld lautet "Vertrag von StratOz GmbH". Mitarbeiter haben so die Möglichkeit über die Organisation den Vertrag in der allgemeingültigen Akte zu Verträgen zu finden oder aber mit der Suche nach "Vertrag StratOz" direkt das richtige Dokument zu finden.

4. Die Abarbeitungsreihenfolge der Sections aus dem import.ini sind entscheidend darüber welche Informationen bereits vorliegen und wiederverwendet werden können. [SYSTEMFIELDS], [REFERENCEFIELDS] und [GLOBAL] werden genau in dieser Reihenfolge eingelesen. Werden Felder bereits gesetzt so stehen diese folglich auch für weitere Felder zum Import zu Verfügung.

5. Temp Felder können jederzeit definiert werden, indem sie mit _TMP_ beginnen werden sie als solche erkannt und nicht als Feld in Corsa erwartet. _TMP_Beschreibung kann aus mehreren Felder der Datenquelle zusammengesetzt (Beispiel: _TMP_Beschreibung = Return "%DokArt% von %OrgName%") und folglich für den Import mit poststukinhood1 = Return %_TMP_Beschreibung% festgelegt werden.

6. Einige Systemfelder werden ausschließlich von Corsa selbst gesetzt. Hierbei ist die Liste der nicht importierbaren Felder zu beachten.

7. LogMessage ist eine Funktion die einen Protokolleintrag erzeugt und bei der Fehlersuche helfen kann. Die Funktion sollte immer nur auf _TMP_ Felder angewendet werden, so dass diese vom Importservice nicht importiert werden.

Nachdem alle Informationen vorliegen kann das Mapping der Felder durchgeführt werden. Hierbei steht in der Section SYSTEMFIELDS immer der Feldname aus Corsa gefolgt von einer TCL Funktion welche den Wert zurückliefert welcher importiert wird. Soll ein Wert statisch importiert werden, so dient die TCl Funktion Return zur direkten Rückgabe des Wertes.

[GLOBAL]
OBJECTID        = Return %_TMP_OBJECTID%
OBJECTKIND      = Return Invoice
OBJECTTYPE      = Return S

[SYSTEMFIELDS]
_TMP_PROT              = LogMessage "Creating Unique ID for [file join \"D:/stratoz/data/\" %OrgFile%]"
_TMP_UniqueID          = ::sha2::sha256 -hex -filename [file join "D:/stratoz/data/" %OrgFile%]
_TMP_OBJECTID          = WebserviceCall ::CreateObject::DocumentByQuery Invoice *DUMMY* [list [list qrtReference dUnique qcAnd qoEqual %_TMP_UniqueID%]] [] [list [list dUnique %_TMP_UniqueID%]]

poststuk.reg_datum     = Return %date%
poststuk.dat_poststuk  = Return %invoicedate%
poststuk.inhoud1       = Return "Invoice of %organisation%"

Gleiches gilt für die Zusatzfelder welche in der Section REFERENCEFIELDS definiert werden.

[REFERENCEFIELDS]
dIBAN                  = Return %iban%
dInvoiceNo             = Return %invoiceno%

[VARTAB]

Damit das Dokument mit der Organisation verknüpft wird muss die ID aus Corsa vorliegen. In diesem Beispiel gehen wir davon aus, dass die IBAN eindeutig ist und wir die Organisation anhand dieser ausfindig machen können. Existiert noch keine Organisation mit dieser IBAN so wird sie als leere Registrierung angelegt und das Dokument verknüpft. Existieren mehrere Organisationen mit dieser IBAN, so werden alle mit dem Dokument verknüpft.

[LINKS]
LINKOBJECTTYPE         = Return E
LINKOBJECTIDS          = WebserviceCall ::CreateObject::OrganisationByQuery CUSTOMER *DUMMY* [list [list [qrtReference oIBAN qcAnd qoEqual %iban%]] {} [list [list oIBAN  %iban%]]

Das Originaldokument wird mit der Funktion ErrorIfNotExists übergeben, damit der Import bei fehlender Datei einen Fehler auslöst und den Administrator informiert. Die Originaldatei dient mit dessen Hashwert als eindeutige Identifizierung, somit ist eine Versionierung in Corsa nicht notwendig und wird fest auf 1 gesetzt.

[UPLOAD]
NAT         = ErrorIfNotExists [file join "D:/stratoz/data/" %OrgFile%]  
NATVERSION  = Return 1

[POSTIMPORT]

[OK]

[ERROR]

Mapping Beispiele

Hier sind noch einige Beispiele die in der Mapping Datei verwendet werden.

[GLOBAL]
; Pay attention Technically the reading process is 1. System fields 2. Reference fields and then global fields
OBJECTID        = %Document Id%
OBJECTID        = Return %_TMP_OBJECTID%
OBJECTKIND      = Return "Retroactum"
OBJECTKIND      = Return %Stuksoort code%
;Actually supported S, D, V, C, E, P
OBJECTTYPE      = Return S 

[SYSTEMFIELDS]
;Generate a Unique ID (SHA256) for the document
_TMP_PROT              = LogMessage "Creating Unique ID for [file join \"D:/stratoz/data/\" %OrgFile%]"
_TMP_UniqueID          = ::sha2::sha256 -hex -filename [file join "D:/stratoz/data/" %OrgFile%]
;In most cases you will have the full path to the import file in the csv. So simply use this instead of the above.
_TMP_PROT              = LogMessage "Creating Unique ID for %OrgFile%"
_TMP_UniqueID          = ::sha2::sha256 -hex -filename %OrgFile%

;Create the document if not present (based on the unique id which will be checked against Corsa) yet, otherways get a new doc id from Corsa
; WebserviceCall ::CreateObject::DocumentByQuery <ObjectKind> <ObjectId> <Query> <SystemFieldsList> <ReferenceFieldsList>
_TMP_OBJECTID          = WebserviceCall ::CreateObject::DocumentByQuery %Stuksoort code% *DUMMY* [list [list qrtReference dUnique qcAnd qoEqual %_TMP_UniqueID%]] [] [list [list dUnique %_TMP_UniqueID%]]
;You will need this if you want to delete the newly created object when an error occours during the import process
_TMP_objectCreated   = CheckDefinition $::mapping::objectCreated

; Setting the system fields
poststuk.reg_datum     = Return %Registratie datum%
poststuk.onderwerp     = Return %Onderwerp%
obj_doc.naam           = Return %Bestandnaam%
poststuk.afgehandeld   = Return %Afg%

;Set current timestamp
poststuk.dat_poststuk  = clock format [clock seconds] -format "\x25\d/\x25\m/\x25\Y"

[REFERENCEFIELDS]
;Here are differences in the source data and Corsa field, so an adjustment from CSV Data to Corsa data is needed to ensure correct spelling.
bouwdsr      = string map {Aanvraag "01 - Aanvraag" Vergunning "02 - Vergunning" Tekening "03 - Tekening" Overige "04 - Overig"} %Bouw document soort%
;Set the Unique ID and an Import Type Version
dUnique      = Return %_TMP_UniqueID%
;If you have the document id in your CSV you can generate the sha here instead of above.
dUnique      = ::sha2::sha256 -hex -filename %OrgFile%
dVersion     = Return "R2C 1.0"

[VARTAB]

[LINKS]
;Real Estate 
LINKOBJECTTYPE         = Return V
LINKOBJECTIDS          = Return %Vastgoed%
;Imports a list of Vastgoed = "ID00001,ID00002"
LINKOBJECTIDS          = split %Vastgoed% \, 

;Folder is linked to the id which is present in the csv
LINKOBJECTTYPE         = Return D
LINKOBJECTIDS          = Return %Dossiers%
;Folder can be created if Foldertype is set to manual so we can set the folder id. Otherwise the folder can be created automaticly and linked to this document registration.
LINKOBJECTTYPE        = Return D
LINKOBJECTIDS         = WebserviceCall ::CreateObject::FolderByQuery Bouw "%Dossiers%" [list [list dossier.dossier_oms "%Dossier titel%"]] {} {}

[UPLOAD]
;Folder structure must be set to the path of %Orgfile%. We do not generate a new version if the file is the same so always version 1 is set.
NAT         = ErrorIfNotExists [file join "D:/stratoz/data/" %OrgFile%]  
NATVERSION  = Return 1
;Use the next available version
NATVERSION  = Return 0
NATMODE     = Return 0
;CORSA won't do a job to create archiv- OCR- or thumb !RESEARCH!
NATDSACTION = subst "-action NONE"

;You can directly import the archive, ocr and thumbnail files if you already have them
ARC         = ErrorIfNotExists %ArcFile%
OCR         = ErrorIfNotExists %OcrFile%
TMB         = ErrorIfNotExists %TmbFile%

[POSTIMPORT]

[OK]

[ERROR]
;If you do not use a unique id to identify the object, you should delete the object when an error occours during the import process and import again when problems are fixed!
CMD          = if {%_TMP_objectCreated%} {WebserviceCall Direct DeleteObject "%OBJECTTYPE%" "%_TMP_OBJECTID %"}