Universal Importer 3.0
Werbung
Universal Importer 3.0 Copyright © 2016 Lexmark. All rights reserved. Lexmark is a trademark of Lexmark International, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark. Inhaltsverzeichnis 1 Einleitung ............................................................................................................. 1 1.1 Funktionen ........................................................................................................... 1 1.2 Vorteile ................................................................................................................. 1 2 Voraussetzungen ................................................................................................. 1 3 Lizensierung ......................................................................................................... 2 4 Installation ........................................................................................................... 2 5 Konfiguration ...................................................................................................... 3 5.1 Konfiguration eines Import-Tasks ...................................................................... 3 5.2 Konfigurationsdatei "importer.properties" ......................................................... 4 5.2.1 Verbindungsart ................................................................................................ 4 5.2.2 Classic Connector Pfad ................................................................................... 5 5.2.3 Daten- und Ausgabeverzeichnis ..................................................................... 5 5.2.4 Benutzerdaten .................................................................................................. 5 5.2.5 Benutzertyp ...................................................................................................... 6 5.2.6 Thread-Login .................................................................................................... 6 5.2.7 Importerthreads ............................................................................................... 6 5.2.8 Importer-Handling nach Import ..................................................................... 6 5.2.9 Timeout ............................................................................................................ 7 5.2.10 Importtyp ......................................................................................................... 7 5.2.11 Dateien für den Import ................................................................................... 7 5.2.12 Datenbankdefinition (DDC) ............................................................................ 7 5.2.13 Dateien-Handling nach Import ...................................................................... 8 5.2.14 Volltextfeld ........................................................................................................ 8 5.2.15 Archivieren von Variablen ............................................................................... 8 5.2.16 Originalformat ................................................................................................. 9 5.2.17 Broker-Einstellungen ....................................................................................... 9 5.2.18 Zeit- und Datumsformat ................................................................................. 9 5.2.19 Plug-In Klasse .................................................................................................. 10 5.2.20 Dateiname ........................................................................................................ 10 5.2.21 Revisionskommentar ....................................................................................... 10 5.2.22 ACL Überprüfung ............................................................................................ 10 5.2.23 Streaming Optionen ........................................................................................ 11 Streaming mit Universal Importer ............................................................... 11 Streaming mit Windows Registry ................................................................. 12 5.3 Spezielle Hinweise zum Import von CSF-Dateien ............................................ 12 5.4 Definition der SAPERION Import-XML-Struktur ............................................... 12 5.5 Konfiguration Logging ........................................................................................ 13 5.5.1 Log4J ................................................................................................................ 13 5.5.2 Log Level .......................................................................................................... 14 Plug-In Technologie ............................................................................................. 14 6.1 Plug-In Methoden ............................................................................................... 15 6.1.1 beforeImport() ................................................................................................. 15 6.1.2 afterImport() .................................................................................................... 15 6.1.3 beforeParse() ................................................................................................... 15 6.1.4 init(), finish() ................................................................................................... 15 6.2 Definition eigener Übernahmeformate .............................................................. 16 7 Starten des Universal Importes .......................................................................... 16 8 Ablauf des Imports .............................................................................................. 16 9 Erzeugen von Ordnerstrukturen ......................................................................... 18 10 Dokumente per CSF-Import revisionieren ......................................................... 18 10.1 Import/ Revise Mechanismus ............................................................................ 19 10.1.1 "DuplicateHandling" ....................................................................................... 20 6 10.1.2 DocumentHandling ......................................................................................... 20 10.1.3 PropertyHandling ............................................................................................ 20 11 Starten von Workflow .......................................................................................... 21 12 Setzen von Systemfeldern .................................................................................. 21 13 Logging und Fehler ............................................................................................. 22 13.1 Logging bei CSF-Importen .................................................................................. 22 13.2 Zusammenfassender Report .............................................................................. 22 13.3 Error Level ............................................................................................................ 22 1.1 Funktionen Universal Importer 3.0 1 Einleitung Der Universal Importer ist in der Programmiersprache Java geschrieben und dient dem massenhaften Import von Dokumenten zusammen mit ihren Indexdaten. Im Gegensatz zum Fast Importer werden die Indexdaten jeweils synchron mit den Dokumenten archiviert, so dass der Import-Vorgang weniger performant als beim Fast Importer abläuft. 1.1 Funktionen Der Universal Importer beherrscht bis auf wenige Ausnahmen, sämtliche Funktionen des Import-Treibers wie z.B.: + das gleichzeitige Speichern mehrerer Dateien in eine Dokumentenstruktur + das Schreiben von Multivalue-Feldern + für TIFF die Unterscheidung von Image- und Applikationsdatei + differenzierte Behandlung von Dubletten + differenzierte Behandlung der Originaldokumente nach dem Import 1.2 Vorteile Der Universal Importer bietet die im Folgenden genannten Vorteile: + Einsatz auch auf Unix-Rechnern aufgrund der Java-Programmierung (basiert auf UBI-Schnittstelle) + der Importer ist auf allen Plattformen lauffähig, die die SAPERION UBI unterstützen. + geeignet für den Einsatz mit Job-Steuerungen + XML-Dateien zusätzlich zu den CSF-Dateien für die Übergabe von Indexdaten + Fehlerbehandlung, Funktions-Logging und -Protokollierung + Multi-Threading und mehrfach startbar + lauffähig als Service/ Daemon mit einstellbarem Polling-Intervall + konfigurierbar über eine Property-Datei ("importer.properties") 2 Voraussetzungen Um den Importer ordnungsgemäß benutzen zu können, müssen folgende Voraussetzungen erfüllt sein: + Auf dem Rechner muss mindestens eine Java Runtime Version 5 installiert sein. Wir empfehlen die Version 1.6. (Diese Java Runtime ist kostenfrei erhältlich unter http://java.sun.com). 1 3 Lizensierung Bitte beachten Sie, dass bei der Benutzung von SAPERION UBI eine 32 Bit Java Runtime verwendet werden muss. + Schreibzugriff auf die Ausgabeverzeichnisse muss vorhanden sein. + Eine weitere wichtige Voraussetzung bei den Import über UBI ist, dass das SAPERION Programmverzeichnis in der Systemvariablen PATH enthalten ist. + Für den Betrieb des Universal Importer über den Classic Connector ist mindestens SAPERION Version 6 erforderlich, außerdem wird ein laufender Java Core Server benötigt. + Für den Betrieb des Universal Importers über UBI wird der Core Server oder Java Core Server vorausgesetzt. + Die Windows-Variable: %JAVA_HOME% muss auf die zu verwendete Java Runtime Installation gesetzt sein. Im Windows-Pfad selber muss dann folgendes eingetragen sein: %JAVA_HOME%\bin 3 Lizensierung Für die Nutzung des Universal Importers muss die Option "Import-Driver" freigeschaltet sein. 4 Installation Der Universal Importer wird als gepacktes Archiv (ZIP) ausgeliefert. Hier finden Sie u.a. für den Importer benötigte .jar-Dateien, "...\Universal_Importer_.zip\lib\jar\". Unter anderem sind es folgende: + UniversalImporter.jar Der SAPERION Importer + log4j-1.2.8.jar Die Log4J-Bibliothek. Zum Starten des Importers wird eine Batchdatei , "...\Universal_Importer_.zip\tasks\template\" befindet, ausgeliefert: + i die sich siehe Verzeichnis im Verzeichnis start_import.bat Da es für den Universal Importer in früheren Versionen zwei .jar-Dateien gab ("importer_common.jar" gibt es nun nicht mehr), müssen Sie bei einem Update ggf. das Startup Skript anpassen. Des Weiteren stellen wir Ihnen die beiden verschiedene Konfigurationsdateien (die in den späteren Kapiteln näher erläutert werden) zur Verfügung. Diese finden Sie im Verzeichnis "...\Universal_Importer_.zip\tasks\template\" + importer.properties 2 5.1 Konfiguration eines Import-Tasks Die Importer-Konfigurationsdatei. i + In bisherigen Versionen des Universal Importers hieß diese Datei "saperion.properties". Falls Sie eine frühere Version dieser Datei haben, müssen Sie diese auf "importer.properties" umbenennen. Mit der Version 3.0 des Universal Importers wird "saperion.properties" nur für die Konfiguration des Classic Connectors benutzt. log4j.properties Die Log4J-Konfigurationsdatei (siehe http://logging.apache.org/log4j). Die Installation des Importers erfolgt mit den folgenden Schritten: 1. Entpacken Sie den Inhalt der ZIP-Datei in das Verzeichnis aus dem der Importer gestartet werden soll. 2. Passen Sie die Startdatei "start_import.bat" an. In dieser Batchdatei werden der Aufruf des Importers sowie die erforderlichen Umgebungsparameter definiert. Über diese Batchdatei erfolgt der Start des Importers. Die anzupassenden Parameter sind in der Batchdatei kommentiert. Bitte beachten Sie, dass bei der Benutzung von SAPERION UBI und der gleichzeitigen Verwendung von 32 Bit und 64 Bit Java Runtime bei der Ausführung des Importers über die Batchdatei der expliziter Pfad zur java.exe in der Batchdatei angegeben werden muss. 3. Passen Sie die Konfigurationsdatei "importer.properties" an die lokale Umgebung an. Nähere Informationen hierzu finden sich in den beiden nachfolgenden Kapiteln. 4. Nehmen Sie die Umbenennung der Datei "saperion_<version>.jar" Datei in "saperion.jar" vor. Dabei steht <version> für die verwendete Java-Version. Diese Dateien befinden sich im Unterverzeichnis "\ubi\java" des SAPERION Programmverzeichnisses. Beispiel: Bei der Verwendung von Java 1.5 muss die Datei "saperion_5.jar" nach "saperion.jar" umbenannt werden, bei Java 1.6 ist es die Datei "saperion_6.jar". 5 Konfiguration 5.1 Konfiguration eines Import-Tasks Um einen Import-Task zu konfigurieren, gehen Sie wie folgt vor: 1. Legen Sie ein neues Verzeichnis "...\SAPERION_Universal_Importer\tasks\". 2. Kopieren Sie alle Dateien aus "...\SAPERION_Universal_Importer\tasks\template\" hierhin. 3. Passen Sie die Batchdatei "start_import.bat" so an, dass die lokale Umgebung angesprochen wird. Es handelt sich um die Anpassung der Pfade zu den Task Konfigurationsdateien, des Universal Importers sowie des SAPERION Application Verzeichnis: 3 hierfür an, z.B. 5 5.2 Konfiguration + Pfad für die Importkonfiguration: "...\SAPERION_Universal_Importer\tasks\" Verzeichnis in + Pfad für den Universal Importer in Java + Pfad zu SAPERION Application: hier befinden sich die Dateien "saubijni.dll" und "libsaubijni.dll" + Pfad für den Classic Connector: Stellen Sie sicher, dass die Versionsnummern (.jarDateiname) der verwendeten SAPERION-Version entsprechen. 4. Passen Sie die Konfigurationsdatei "importer.properties" entsprechend Ihren Anforderungen an (siehe Kapitel "Konfigurationsdatei 'importer.properties'", unten). 5. Passen Sie die "log4j.properties" an, um den lokalen Speicherort festzulegen. Z.B. "log4j.appender.file.File=\\\\Server\\directory\\import.log". 6. Setzen Sie in der "log4j.properties" auch die Protokollstufe (log level) (siehe Kapitel "Log Level" unten). Konfigurationsdatei "importer.properties" Bevor der Universal Importer gestartet werden kann, muss er über die Datei "importer.properties" konfiguriert werden. Diese finden Sie im Unterverzeichnis "...\tasks\template". Diese Datei ist im normalen Java-Properties-Format .properties-Konfigurationsdateien haben die Form gehalten. Die Einträge in den <name> = <Wert> Im Folgenden werden die einzelnen Einträge der "importer.properties" beschrieben. 5.2.1 Verbindungsart # class name for Connector: wether the importer connects to saperion by ubi or classicconnector # connectorClass = com.saperion.universalimporter.importer.impl.ConnectWithCC connectorClass = com.saperion.universalimporter.importer.impl.UBIConnector Über diesen Parameter wird die Art der Verbindung gesteuert. Mögliche Werte sind: + com.saperion.universalimporter.importer.impl.UBIConnector + com.saperion.universalimporter.importer.impl.ConnectWithCC ! Wenn der Universal Importer mit dem Classic Connector betrieben wird, stehen folgende Funktionen nicht zur Verfügung: Records Management, Dokumentvariablen, Import von strukturierten Dokumenten. 4 5.2 Konfigurationsdatei "importer.properties" Wenn die Verbindung über den Classic Connector erfolgen soll, muss bei diesem Parameter der Pfad zu den Konfigurationsdateien des Classic Connectors angegeben werden (siehe "Classic Connector Pfad"). 5.2.2 Classic Connector Pfad # path from which the UI initializes the classicconnector, only important when connectorClass is classicconnector (CC) # ccConfigPath= Dieser Parameter ist nur relevant, wenn connectorClass=classicconnector (cc). Hier wird der Pfad angegeben, von wo aus der Importer den Classic Connector initialisiert. 5.2.3 Daten- und Ausgabeverzeichnis # directories for import data ( input ) and managed data ( output ) input_directory = \\\\Server\\directory\\directory\\ output_directory = \\\\server\\directory\\directory\\out Über den Parameter "input_directory" definieren Sie das Verzeichnis, in dem sich die zu importierenden XML-/CSF- und Datendateien befinden (Datendateien müssen sich dabei nicht hier befinden, sondern ihr Ort muss relativ zu diesem Verzeichnis angegeben werden). Über den Parameter "output_directory" definieren Sie das Verzeichnis, in das bearbeitete Dateien verschoben werden. Erfolgreiche Imports werden (in Abhängigkeit vom Parameter "ImportHandling") in das Unterverzeichnis "Ok" verschoben bzw. kopiert. Fehlgeschlagene werden in die entsprechenden Fehlerverzeichnisse abgelegt. Diese sind: + INPUT_ERR, REJECTED_ERR + SYSTEM_ERR, EXTERNAL_ERR + REVISION_ERR + WORKFLOW_ERR + FEATURE_NOT_SUPPORTED_ERR i Der Benutzer, der den Importer startet, muss Lese- und Schreibrechte auf die Daten- und Ausgabeverzeichnisse besitzen. 5.2.4 Benutzerdaten # user credentials for importer - this user account have to exist in saperion system # client only in mandatory systems username = <name> password = <password> # client = System 5 5 Konfiguration In dieser Sektion werden die Benutzerdaten zur Anmeldung an SAPERION definiert: + Benutzername und Passwort + Sofern es sich um ein mandantenfähiges System handelt, geben Sie den Mandantennamen für das Login an. 5.2.5 Benutzertyp # usertype indicates which saperion client user type should be used for the importer, usertype = 16 Folgende Werte können angegeben werden: Benutzertyp Wert Beschreibung 1 Index 3 Universal/ Administrator 16 API Index 5.2.6 Thread-Login # allow threadlogin # threadLogin = TRUE 5.2.7 Importerthreads # number of parallel import threads, can be increased on high performance machines, you need a client license per thread number_of_threads = 1 Die Anzahl der gleichzeitig zu startenden Importerthreads. 5.2.8 Importer-Handling nach Import # enable this flag if importer shouldn't stop after import job # continuous = true Mit diesem Parameter wird definiert, wie sich der Importer verhalten soll, wenn alle Dateien importiert wurden. 6 5.2 Konfigurationsdatei "importer.properties" Importer -Handling nach dem import Wert Beschreibung TRUE Der Importer bleibt weiter aktiv und überwacht das Verzeichnis auf neue, zu importierende Dateien. FALSE 5.2.9 Der Importer wird beendet (Standardeinstellung). Timeout # time in milliseconds the importer checks for new files timeout = 10000 Zeit in Millisekunden, die der Importer wartet, wenn er im Eingabeverzeichnis keine Dateien zum Importieren vorfindet. 5.2.10 Importtyp # ImportType options: CSF, XML. Default: XML # ImportType=CSF Folgende Werte können angegeben werden: + CSF + XML (Standardwert) 5.2.11 Dateien für den Import # fileExtension defines the extension of the files which should be included during the import, default: .xml for XML, .csf for CSF # fileExtension=.abc Über diesen Parameter wird die Dateiendung der Dateien definiert, die beim Import berücksichtigt werden sollen. Standardmäßig sind die Dateiendungen ".xml" für XML-Dateien und ".csf" für CSF-Dateien eingestellt. i Die Dateiendung muss immer mit Punkt anzugeben werden, also z.B. fileExtension=.abc 5.2.12 Datenbankdefinition (DDC) # name of saperion index table (ddc without fil-extension), only evaluated for CSF import # DBName = <Definitionname> 7 5 Konfiguration Name der SAPERION-Datenbankdefinition (DDC), in welche die Dateien importiert werden sollen. i Dieser Parameter wird nur beim Import von CSF-Dateien ausgewertet. Beim XML-Import muss der Name der DDC im Tag <definition> angegeben werden. 5.2.13 Dateien-Handling nach Import # ImportHandling options: NOTHING, MOVE, DELETE. Default: MOVE # ImportHandling = MOVE Über diesen Parameter wird definiert, was nach dem Import einer Datei passieren soll. Dabei gibt es folgende Varianten: Dateien-Handling nach dem Import Wert Beschreibung NOTHING Bei diesem Wert verbleiben die Dateien an ihrem Ort (Standardwert). MOVE Die Dateien werden nach dem Import aus dem "In"- Verzeichnis in das Verzeichnis "Out\ Ok" verschoben. DELETE Die Dateien werden nach dem Import gelöscht. 5.2.14 Volltextfeld # only evaluated for CSF import # FTField = Full_Text Hier kann das Volltextfeld der DDC angegeben werden, in das der Textinhalt der übergebenen Applikationsdatei (z.B. PDF) gespeichert werden soll. ! Dieser Parameter wird nur beim CSF-Import ausgewertet. Beim XML-Import muss das Volltextfeld in der XML-Datei im Tag <fulltextfield> angegeben werden. 5.2.15 Archivieren von Variablen # attribut fields which are not defined in the ddc can be archived as SAPERION variables # allowVariables=TRUE 8 5.2 Konfigurationsdatei "importer.properties" Archivieren von Variablen Wert Beschreibung TRUE Über XML und CSF-Dateien können auch Variablen mit dem Dokument archiviert werden. Dabei werden vom Importer alle Felder innerhalb von <indexdata>..</indexdata> als Variablen archiviert, die nicht in der DDC als Feldname vorhanden sind. 5.2.16 Originalformat # LoadOriginal property for images: true - keep original file format, false - convert with lead tools # loadoriginal = TRUE Originalformat Wert Beschreibung TRUE Die übernommenen Image Dateien werden im Originalformat belassen. FALSE Konvertieren der Dateien mit den Lead-Tools und Übernahme dieser konvertierten Datei. 5.2.17 Broker-Einstellungen Dieser Pflicht-Parameter muss gesetzt werden, damit eine Verbindung zum Broker aufgebaut werden kann. ! Wenn Sie keine Keys definieren, verwendet der Universal Importer "localhost" und den Standardport "12347". Beispiel # Broker/Core is alive detection BrokerServerName=<IP Adress Broker/Core server> # Port Option Default: BrokerPortNumber=12347 # BrokerPortNumber=12347 BrokerPortNumber=4711 Broker-Einstellungen Parameter Beschreibung BrokerServerName IP-Adresse des Broker Servers. Wenn hier kein Server Name definiert wird, wird auf den "localhost" zurückgegriffen. BrokerPortNumber Broker Portnummer. Wenn hier keine Portnummer angegeben wird, wird der Standard Port 12347 genommen. 5.2.18 Zeit- und Datumsformat # Pattern for date, time and datetime format. If this values are not set, the importer use the system pattern. 9 5 Konfiguration dateformat = dd.MM.yyyy timeformat = HH:mm:ss datetimeformat = dd.MM.yyyy HH:mm:ss Hier können Sie das Datums- und Zeitformat angeben. Wenn keine Vorgaben gesetzt sind, wird das Format des Systems benutzt. 5.2.19 Plug-In Klasse # pluginClass = <Class name> Der Universal Importer bietet die Möglichkeit, eigene Plug-Ins für die Datenübernahme einzubinden. Ein Plug-In ist eine Java-Klasse. Die Java-Klasse ist dabei eine Implementation der Plug-In-Schnittstelle "ImporterPlugin.java". Dieses Interface findet sich im Package "com.saperion.universalimporter.intf" (siehe auch Kapitel "Plug-in Technologie" unten). Um ein Plug-In nutzen zu können, müssen Sie hier den Klassennamen eingeben. 5.2.20 Dateiname # shortfilename = TRUE 5.2.21 Revisionskommentar Sie können optional einen Standardkommentar eintragen, der zu jeder Revision angehängt wird. Beispiel: DefaultRevisionComment=My comment 5.2.22 ACL Überprüfung Optional können Sie einen Parameter setzen, um zu prüfen, ob alle ACLs in SYSACLLIST in SAPERION vorhanden sind. CheckACLs=TRUE Wenn es keinen Eintrag gibt, wird der Wert FALSE angenommen. ! Das Revisionieren von Dokumenten setzt voraus, dass der Benutzer, unter dem der Universal Importer angemeldet ist, auch revisionieren darf. Das heißt, dass er in der entsprechenden ACL am Dokument auch eingetragen sein muss. Anderenfalls kommt die Fehlermeldung ""10 - Access denied" in den Logs. 10 5.2 Konfigurationsdatei "importer.properties" Wird der Universal Importer unter UBI eingesetzt, so können auch ACL-Listen zum Einsatz kommen (mehr als eine ACL). In diesem Fall müssen die Trennzeichen für die ACLs spezifiziert werden. SeparationCharacter2=; Der Universal Importer prüft, ob die optionale Property "SeparationCharacter2" definiert ist 5.2.23 Streaming Optionen 5.2.23.1 Streaming mit Universal Importer Ab der Universal Importer Version 3.1.64798 kann ein Dokument anhand seines Mime-Types in SAPERION als Stream archiviert werden. Die Streaming Option kann über den Parameter streaming=TRUE in der importer.properties Datei angeschaltet werden. Default ist FALSE. Für die Streaming Funktionalität wird der Classic Connector ab SAPERION Version 7.1 SP3 benötigt. Falls ein nicht kompatibler Classic Connector bei angeschalteter Streaming-Funktion verwendet wird, wird das Dokument nicht importiert und in dem Error Verzeichnis SYSTEM_ERR im Output-Verzeichnis abgelegt. Jeder Mime-Type muss zum Aktivieren der Streaming-Funktion zusätzlich in der importer.proerties aufgelistet und auf TRUE gesetzt werden. Beispiel: image/bmp = TRUE application/msword = TRUE Der UI benutzt zur Identifizierung des Mime-Types für den Import die Dateiendung der zu importierenden Datei. Dazu verwendet der UI die mime.types Property-Datei. Es muss sichergestellt werden, dass diese Datei im Classpath des UI liegt. Beispiel aus der Datei mime.types: image/bmp bmp application/msword doc dot Mit dieser Beispiel Konfiguration werden Dateien mit der Endung .bmp als Mime-Type image/bmp erkannt und die SAPERION Streaming-Funktion beim Import aktiviert. Nicht bekannte Dokumenten Typen könne je nach Konfiguration des Parameters „streaming.unknown.types“ in der 11 5 Konfiguration importer.properties gestreamt werden (TRUE) oder nicht gestreamt werden (FALSE). Der Default-Wert für nicht bekannte Typen ist TRUE. 5.2.23.2 Streaming mit Windows Registry Dokumente Typen, die in der Windows Registry unter dem root key HKEY_CLASSES_ROOT einen Eintrag „Content Type“ haben, können vom Streaming ausgeschlossen werden. Folgender Parameter muss in der importer.properties Datei eingestellt werden: streaming.lookup.windows.registry=TRUE Default Einstellung ist TRUE und aktiviert die Überprüfung der Windows Registry. Dazu überprüft der Universal Importer, ob es in der Windows Registry der Lokalen Windows Maschine für den Dokumenten Typ (z.B. .bmp) einen Eintrag für „Content Type“ gibt. Ist ein Eintrag vorhanden wird der Dokument Typ zu den bekannten Mime-Types hinzugefügt und nicht als SAPERION Stream abgelegt. 5.3 Spezielle Hinweise zum Import von CSF-Dateien Im CSF-Import des Universal Importers kann innerhalb von Feldnamen und Feldwerten das Trennsymbol (üblicherweise '@') mit dem Symbol '"' maskiert werden. Das gilt ebenso für das Maskierungssymbol '"'. Beispiel: Die Zeile "aaa@bbb@c""c"@c""@d@""""e"""@ee@fff" würde also folgende Feldnamen definieren: aaa @ bbb @ c"c@c" @ d @ ""e"@ee @ fff 5.4 Definition der SAPERION Import-XML-Struktur Die vom Universal Importer vorausgesetzte XML-Struktur wird anhand eines Beispiels erläutert. Beispiel: <?xml version="1.0" encoding="UTF-8"?> <document> <definition>testddc</definition> 12 5.5 Konfiguration Logging <acl>name_of_acl</acl> <indexdata> <attr1>value_of_attr1</attr1> <attr2>value_of_attr2</attr2> </indexdata> <appfile>example.pdf</appfile> </document> XML-Struktur Paramater Beschreibung <document> ... </document> Anfang und Ende des Bereichs der Dokumentendefinition, in dem die folgenden weiteren Definitionen erfolgen Definition Name der DDC ACL_Name Name der ACL, die dem Dokument zugeordnet werden soll appfile Name der zu importierenden Applikationsdatei docfile Name der zu importierenden Bilddatei Hinweis: Unter Unix wird der Import und die Bearbeitung von Bilddateien nicht unterstützt <indexdata> ... </indexdata> Anfang und Ende der Indexdatendefinition FieldNameX Name des DDC-Feldes, in das der Index-Wert (Data) geschrieben wird. Diese Zeilen müssen innherhalb des Bereichs der <indexdata> geschrieben werden. Wenn mehrere Dateien (Image oder Applikationsdateien) übernommen werden sollen, müssen die einzelnen Namen innerhalb des entsprechenden Tags durch ">" getrennt werden. Beispiel: <appfile1>file1.pdf</appfile1> <appfile2>file2.tif</appfile2> <appfile3>file3.doc</appfile3> 5.5 5.5.1 Konfiguration Logging Log4J Der Logging-Mechanismus des Importers baut auf dem Log4J-Framework auf, welches von der Apache Software Foundation entwickelt wurde (siehe http://logging.apache.org/log4j). Dieses Framework ist ein weit akzeptierter Standard für das Logging in Java-Umgebungen. Alle von einem modernen Logging-System erwarteten Features wie dateiübergreifende Logs, verschiedene Logstufen etc. sind hier implementiert. Log4J kann über die Datei "log4j.properties" konfiguriert werden; für Details siehe die Webseite über diese Konfiguration. Hier kann auch der Log-Level gesetzt werden; ausführliches Logging des Importers beinhaltet unter anderem 13 6 + das Markieren von Dateien der verschiedenen Importer + Wartezeiten der Importer + Erfolgs- und Misserfolgsmeldungen nach jedem Import Plug-In Technologie Fehler werden sehr direkt behandelt; wenn ein Import fehlschlägt, werden die entsprechenden Dateien sofort in das Error-Verzeichnis verschoben. i Wenn der Parameter ImportHandling=NOTHING gesetzt ist, werden fehlerhafte Dateien nicht verschoben. 5.5.2 Log Level In der Konfigurationsdatei "log4j.properties" können Sie anhand des folgenden Parameters den Log Level definieren. log4j.rootLogger= Log Level Log Level Beschreibung all alle Levels inklusive der benutzerdefinierten Levels trace Nur Entwicklung: Programmablauf anzeigen debug Nur Entwicklung: Ausgabe der Debugging Meldungen info grobe, eher selten geschriebene Informationen warn kleiner Anwendungsfehler oder unerwartetes Verhalten, nachdem die Anwendung normal weiter läuft error Anwendungsfehler und Exception, nach denen die Anwendung weiterlaufen kann, aber möglicherweise ein Teil der Anwendung nicht funktioniert fatal Anwendungsfehler, nach denen die Anwendung nicht mehr weiterlaufen kann no kein Logging 6 Plug-In Technologie Der Universal Importer bietet die Möglichkeit, eigene Plug-Ins für die Datenübernahme einzubinden. Ein Plug-In ist eine Java-Klasse. Die Java-Klasse ist dabei eine Implementation der Plug-In-Schnittstelle "ImporterPlugin.java". Dieses Interface findet sich im Package "com.saperion.universalimporter.intf". Um ein neues Plug-In nutzen zu können, müssen Sie in der "importer.properties"-Datei folgenden Eintrag hinzufügen: pluginClass=<Klassenname> 14 6.1 6.1 Plug-In Methoden Plug-In Methoden Das Interface stellt drei grundsätzliche Methoden zur Verfügung: + beforeImport() + afterImport() + beforeParse() Alle drei Methoden bekommen das jeweils gültige SaperionConnector Objekt des Threads als Parameter übergeben. Bei "afterImport()" und "beforeImport()" wird außerdem das ImportDescription Objekt als Parameter übergeben. 6.1.1 beforeImport() Die Methode "beforeImport()" gibt einen Boolean-Wert zurück. Bei der Rückgabe von FALSE wird der Import nicht ausgeführt. Damit ist es zum Beispiel möglich, beim Fehlschlagen von vorgelagerten Validierungen die Ausführung des Imports zu unterbinden. 6.1.2 afterImport() Mit der Methode "afterImport()" wird das Verhalten nach Ausführung des Imports definiert. 6.1.3 beforeParse() Die Methode "beforeParse()" wird noch vor dem Einlesen einer Import-Datei ausgeführt und gibt einen Boolean-Wert zurück. Bei der Rückgabe von FALSE wird der Import nicht ausgeführt. Damit ist es zum Beispiel möglich, vor dem Import eine XSL-Transformation auf eine XML-Datei anzuwenden. 6.1.4 init(), finish() Neben diesen Methoden gibt es noch zwei Standardmethoden: "init()" und " finish()". Die Methode "init()" dient der Initialisierung mit den entsprechenden Konfigurationsdateien. i Nur der Methode "init()" wird die Konfiguration des Universal Importers als Parameter übergeben. "init()" liefert einen Boolean-Wert zurück. Bei der Rückgabe von FALSE wird der Import abgebrochen. 15 7 Starten des Universal Importes Die Methode "finish()" dient dem Aufräumen nach dem Import. 6.2 Definition eigener Übernahmeformate Die Plug-In Technologie des Universal Importers bietet zusätzlich die Möglichkeit, neben XML und CSF eigene Übernahmeformate zu definieren. Hierfür muss wieder eine eigene Java-Klasse geschrieben werden, die in diesem Fall eine Implementierung des Interfaces "com.saperion.universalimporter.intf.ImportReader.java" ist. Das Interface enthält nur eine Methode: readValues() "readValues()" wird überschrieben, um aus einer Datei, deren Name an sie übergeben wird, die Import-Informationen zu lesen. Um für den Import das neue Format zu verwenden, müssen in der "importer.properties" folgende Einträge ergänzt bzw. geändert werden: readerClass=<Klassenname> ImportType=CUSTOM ! 7 Die Klasse ist immer mit vollem Packagenamen anzugeben. Starten des Universal Importes Der Universal Importer wird durch den Aufruf der Batchdatei "start_import.bat" als Prozess gestartet. i 8 Für den Fall, dass er unter Windows als Service oder unter Unix als Daemon laufen soll, ist hierzu der Einsatz zusätzlicher Software notwendig. Sprechen Sie uns für eine Empfehlung an. Ablauf des Imports Der Universal Importer fragt regelmäßig das Eingabeverzeichnis nach neuen XML- oder CSF-Dateien ab (entsprechend der Einstellung des Parameters "continuous"). Wird keine solche Datei gefunden, wartet der Importer eine vordefinierte Zeit lang und fragt dann wieder das Verzeichnis ab. Sobald eine gültige Datei gefunden wird, wird diese markiert, damit keiner der anderen evtl. gleichzeitig laufenden Importer sie benutzen kann und Dateien doppelt verarbeitet werden. Da XML-Dateien im Gegensatz zu CSF-Dateien nur jeweils Daten zu einem Dokument enthalten, werden diese Dateien über eine Stapelverarbeitung behandelt, die im Folgenden beschrieben wird. 16 6.2 i Definition eigener Übernahmeformate Beim XML- und CSF-Import werden zu importierende Dateien auch im Unterverzeichnissen unterhalb des Verzeichnisses "in" gesucht. Eine gültige XML- oder CSF-Datei enthält alle nötigen Metadaten sowie den Namen der Datendatei, die importiert werden soll, relativ zum Verzeichnis der XML- oder CSF-Datei. Die Dateien können auch im Unicode sein; Java und XML unterstützen dies nativ. Nach Abschluss der Konfiguration (siehe Kapitel "Konfiguration") kann der Importer gestartet werden. Die Metadaten werden ausgelesen und in die Datenbank geschrieben, die Datendatei in das Archiv übernommen. Treten hierbei Fehler auf, werden diese entsprechend behandelt (siehe Kapitel "Logging und Fehler"). Dateien fehlgeschlagener Imports werden in die Fehlerverzeichnisse ("INPUT_ERR","REJECTED_ERR","SYSTEM_ERR", "EXTERNAL_ERR", "WORKFLOW_ERR") unter dem Ausgabeverzeichnis verschoben, um manuell überprüft zu werden. All diese Vorgänge werden protokolliert. Für erfolgte Importläufe wird eine "akn"-Datei in das Unterverzeichnis "...\out\Acknowledge" geschrieben. Solange diese "akn"-Datei nicht gelöscht wird, wird die entsprechende Importdatei nicht noch einmal importiert. Nach dem Import werden die Dokumente importiert, die noch von diesem Importer markiert wurden. Anschließend beginnt der Importer wieder damit, Dateien zu suchen und zu markieren. Die folgende schematische Darstellung des Importers beschreibt den Ablauf bei Verwendung von XML-Dateien. Abb. 8–1: Strukturdiagramm Universal Importer (XML) 17 9 9 Erzeugen von Ordnerstrukturen Erzeugen von Ordnerstrukturen Mit dem Universal Importer können auch Ordnerstrukturen in SAPERION erzeugt werden. Dafür müssen die übergeordneten Ordner eines Dokumentes durch "*" getrennt werden. Im nachfolgenden Beispiel wird durch die Syntax zwischen <appfile> und </appfile> folgende Ordnerstruktur erzeugt: i Ordnerstrukturen können nur erzeugt werden wenn der Universal Importer über UBI läuft. Abb. 9–1: Beispiel: Per Importer erzeugte Ordnerstruktur <?xml version="1.0" encoding="UTF-8" ?> <document> <definition>testddc_simple</definition> <indexData> <STRING100>Filetyp Office</STRING100> <INTEGER4>2008</INTEGER4> <DATE6>18.08.2008</DATE6> <STRING100_MV>Berlin;Rom;London;Paris;Warschau;Madrid;Prag</STRING100_MV> </indexData> <appfile>Office*Word*DOC01.DOC>Office*Word*DOC02.DOC>Office*Word*DOC03.DOC>Office*Excel*XLS01.XLS> Office*Excel*XLS02.XLS>Office*Excel*XLS03.XLS>Office*Powerpoint*PPS01.pps>Office*Outlook*MSG01.MSG</ appfile> <acl /> <fulltextfield>Full_Text</fulltextfield> </document> i Bitte beachten Sie, dass im - Gegensatz zur UBI-Schnittstelle - mit dem Classic Connector keine tieferen Strukturen oder Unterordner abgelegt werden können. Strukturen mit einer Unterebene sind jedoch möglich. 10 Dokumente per CSF-Import revisionieren Es ist möglich, Dokumente in SAPERION per CSF-Import zu revisionieren. Hierzu ist es erforderlich, die Headerzeile der entsprechenden CSF-Datei anzupassen, da die Revisionierung gemäß dieser erweiterten Zeile erfolgt. 18 10.1 Import/ Revise Mechanismus Im Folgenden wird exemplarisch eine Headerzeile mit der dazugehörigen Beschreibung näher erläutert. Beispiel: @AI@Mahn_IDX@;REVISEONLY;REPLACEALL;UPDATE@MandantNr Beispiel: Header-Zeile Slot Beschreibung 1=AI siehe CSF Spezifikation 2=Mahn_IDX DDC (ist hier kein Eintrag vorhanden, wird auf die Fallback Definition in der Konfigurationsdatei "importer.properties" zurückgegriffen) 3=;REVISEONLY;REPLACEALL;UPDATE char 1: Separator für slot 3 und slot 4 (in diesem Fall ";") nach char1: enthält die bekannten 3 Handlings in fest vorgegebener Reihenfolge: DuplicateHandling, DocumentHandling, PropertyHandling (Beschreibung siehe unten) mit dem definierten Separator getrennt. 4=MandantNr Liste mit Schlüsselfeldern, die verwendet werden sollen, um die Dokumente im Archiv aufzuspüren. Diese werden mit AND verknüpft. Die aktuellen Werte dieser Property in der CSF-Datei werden dabei herangezogen. Spaltennamen aus Slot 4 können alternativ in der Konfigurationsdatei "importer.properties" konfiguriert werden. Trennzeichen ist hier ';': DuplicateKeyFieldNames= i DuplicateKeyFieldNames wird nur gebraucht, wenn überhaupt revisioniert werden soll, das heißt wenn DuplicateHandling = REVISE oder REVISEONLY. 10.1 Import/ Revise Mechanismus Die eingetragenen Werte in Slot 3 konfigurieren den Import/Revise Mechanismus. Wenn für eine CSF-Datei in Slot 3 keine Werte gefunden werden, dann wird in der "importer.properties" Konfigurationsdatei geprüft, ob Standardwerte definiert worden sind. Wenn auch diese Properties nicht gesetzt sind (da optional), werden folgende Defaulteinstellungen genommen: DuplicateHandling=IGNORE DocumentHandling=APPEND PropertyHandling=OVERWRITE 19 10 Dokumente per CSF-Import revisionieren 10.1.1 "DuplicateHandling" Mit "DuplicateHandling" definieren Sie, wie grundsätzlich mit Duplikaten im Archiv umgegangen werden soll. Dabei ist ein Duplikat als Stammdokument zu verstehen - es bezeichnet das Dokument in SAPERION, zu dem das zu importierende Dokument als Revision hinzugefügt werden soll. Folgende Parameter können gesetzt werden: "DuplicateHandling" Parameter Beschreibung IGNORE Importieren sofern alle Pflichtfelder ausgefüllt sind REVISE Revision erzeugen, wenn Duplikat im Archiv gefunden wird. Wird kein Duplikat gefunden, wird als neue Instanz importiert REVISEONLY Es soll immer versucht werden, eine Revision zu erzeugen. Wenn kein Duplikat im Archiv gefunden wird, dann wird es als (neuer) Fehler behandelt: REVISION_ERR, welcher in einem eigenen Ordner angelegt wird. 10.1.2 DocumentHandling Mit "DocumentHandling" definieren Sie, wie mit den vorhandenen Dokumenten (Dateien) im SAPERION Dokumentobjekt umgegangen werden soll im Falle einer Revision. Folgende Parameter können gesetzt werden: "DocumentHandling" Parameter Beschreibung REPLACEALL Zunächst wird alles gelöscht, danach wird/ werden die neue Datei(en) eingefügt. APPEND Die neue(n) Datei(en) wird/ werden angehängt. 10.1.3 PropertyHandling Mit "PropertyHandling" definieren Sie, wie die Properties, die in der CSF-Datei definiert sind, auf dem SAPERION Dokument übernommen werden sollen. Folgende Parameter können gesetzt werden: "PropertyHandling" Parameter Beschreibung UPDATE Nur wenn die Property x in der CSF Datei nicht leer ist, wird der Wert von x am Dokument geschrieben. Ist diese leer, wird sie übersprungen. 20 10.1 Import/ Revise Mechanismus Parameter Beschreibung OVERWRITE Sämtliche Properties aus der CSF Datei werden geschrieben, unabhängig davon, ob sie in der CSF leer sind oder nicht. Hinweis: Wenn kein Wert für SYSACLLIST übergeben wird (SYSACLLIST Spalte vorhanden aber keinen Wert drin), dann wird die ACL vom Dokument entfernt. Voraussetzung ist, dass der Benutzer, unter dessen Konto der Importer läuft, auch ACLs an Dokumenten ändern darf. 11 Starten von Workflow Durch Setzen des Systemfeldes SYSDOCFLOWDATA können Sie einen Workflow starten. Wenn der Start eines solchen Workflows scheitert, wird die XML-Datei bzw. die Zeile der CSF-Datei, deren Import den Start des Workfloww initiiert hat, im Fehlerverzeichnis WORKFLOW_ERR abgelegt. Außerdem wird die Anzahl der Workflow-Fehler in der abschließenden Ausgabe mit aufgeführt. 12 Setzen von Systemfeldern Der Universal Importer unterstützt auch das Setzen von SAPERION Systemfeldern. Für die Übernahme werden die Systemfelder analog zu anderen Indexfeldern in der Importstruktur definiert. Es werden dabei folgende Systemfelder berücksichtigt: + SYSCUSTOMICONNAME + SYSCONTENTTYPE + SYSDISPOSITIONTIME + SYSDOCFLOWDATA + SYSINDEXSTATE + SYSLCMSTAGE + SYSLITIGATIONHOLD + SYSOUTLINERDATA + SYSRETENTIONCLASS + SYSRETENTIONTIME i Wenn der Universal Importer sich mit UBI verbindet und eine SAPERION Version mit aktiviertem Feature "Records Managment" verwendet wird, wird zum Setzen des Indexwertes SYSRETENTIONTIME die API-Funktion verwendet. Wenn die Verbindung über den Classic Connector erfolgt, ist das Feature "Records Managment" nicht verfügbar. 21 13 13 Logging und Fehler Logging und Fehler Der Universal Importer schreibt wie alle anderen Import-Funktionen von SAPERION Logdateien. 13.1 Logging bei CSF-Importen Beim CSF-Import werden die Einträge in der CSF-Datei geteilt in einen Teil, bei dem der Import ohne Fehler erfolgte ("OK-Verzeichnis") und einen Fehlerteil ("Error Verzeichnis"). Im Fehlerfall werden die importierten Dokumente ebenfalls in das "Error Verzeichnis" verschoben. Im "OK-Verzeichnis" sind hingegen die erfolgreichen Imports wiederzufinden. Ab der UI Version 3.1.64798 werden die CSF-Logdateien in den entsprechenden Verzeichnissen nur dann angelegt, wenn ein Import den dazugehörigen Status erhält. Ein Error Logverzeichnis bleibt daher nach einem Import leer, wenn alle Dokumente erfolgreich importiert werden konnten. Mögliche Fehler sind unter anderem: + Die Metadaten sind korrupt oder passen nicht auf die Definition, die in der Konfiguration angegeben ist. + Fehlende Schreib- oder Leseberechtigungen auf die involvierten Verzeichnisse + Ein SAPERION Server ist unerreichbar. + Die Archivierung von Dokument oder Metadaten schlug fehl. 13.2 Zusammenfassender Report Nach Abschluss des Imports wird ein zusammenfassender Report ausgegeben. Dieser Report enthält folgende Informationen: + Umfang und Dauer des Imports (Imported x MB of data in x seconds) + Anzahl der erfolgreich importieren Objekte (Objects imported successfully) + Anzahl der Systemfehler (System errors) + Anzahl der Datenfehler (data errors): + Anzahl der Fehler mit eindeutigen Feldern (Unique constraint violation errors) + Anzahl der Fehler, die über eigene Plugins gemeldet werden (Externally triggered errors) + Dokumente / Minute (Documents / min) + MB/min 13.3 Error Level Nach dem Import wird ein entsprechender Exit Code (Error level) gesetzt. Dieser Exit Code kann folgende Werte haben: 22 13.3 Error Level Error level Wert Beschreibung 0 alles erfolgreich importiert 1 es traten mehrere Fehler unterschiedlichen Typs auf 2 es wurden ein oder mehrere Dateien nicht importiert, da für sie bereits ".akn"-Dateien existieren 3 es traten ein oder mehrere Fehler auf, die im Protokoll beschrieben sind, aber der Importer hat für keinen Import eine ".akn"-Datei gefunden. i Der Fehlercode 2 wird von Scripten als Fehler gewertet. 23
