CURSOR-Importer

Installationsdokumentation

Allgemeine Hinweise

Beim CURSOR-Importer handelt es sich um ein optionales Software-Program, welches separate Lizenzierung erfordert.

• Es wird immer die aktuellste Version ausgeliefert

• Importiert wird konfiguriert über die Datei configuration.bat (Hier kann die Sprache der Oberfläche geändert werden. Bisher wird Englisch und Deutsch unterstützt.)

• Importiert wird gestartet über die Datei run.bat
  Die run.bat verweist auf ein im Ordner des Importers liegendes Java Runtime Environment. Es sollte im Ordner jre liegen. Sollte dies nicht enthalten sein wird unter Program Files (x86)\Java\<passende jre Version>\ nach einem JRE gesucht. Ist auch dort nichts installiert, wird sich der Importer nicht starten lassen. In diesem Fall das JRE <passende jre Version> von der offiziellen Seite herunterladen und den Unterordner jre des Importers anlegen.

• Über die Datei run_cmd.bat kann der Import von einer oder mehreren bereits erstellen XML Import Dateien gestartet werden. Dazu müssen die entsprechenden Einstellungen in der configuration.bat gesetzt werden.

Installation beim Kunden

• Die auszuliefernden Dateien liegen unter  f:\Install\Java\KopiervorlageFuerAuslieferung\CURSOR Importer\<CRM Hauptversion>\<CRM Patch Version>. Darin sind das Tool und die Voreinstellungen enthalten.

• Die Beispieldaten können zusätzlich aus dem Ordner  f:\Inhaus\Text\900 Entwicklung\Importer\Beispieldaten\ kopiert werden.

• Die Installation beim Kunden erfolgt durch Kopieren der enthaltenen Dateien.

•  Standardmäßig liegt ein Truststore "truststore_cursor.p12" im Hauptordner. Dieser ist durch den Truststore des Kunden, der auch im RichClient liegt, zu ersetzen. Dazu wird der Truststore kopiert und in der configuration.bat angegeben. Andernfalls ist der Zugriff über den WebService nicht möglich.

Aufruf als externer Aufruf

Sofern gewünscht, kann das Tool auch mittels externem Aufruf (vom Typ EXE) gestartet werden, bei dem das Kommando auf die run.bat verweist.

Verwendung der Templates

Aktuell gibt es drei Templates für den Import von Aktivitäten, Geschäftspartnern und Produkten. Diese Templates werden jeweils mit Beispieldateien zu Orientierung ausgeliefert.

Die Struktur ist so aufgebaut, dass es einen Ordner für jede Vorlage gibt, worin Beispielquelldaten (*_Import.csv), eine passende Konfigurationsdatei (*_conf.xxic) und eine Vorlage (*_template.xml) enthalten sind.

Vorhandene Templates:

• ACT_template.xml
  Dieses Template generiert Aktivitäten, welche an Mitarbeiter delegiert sind und die enthaltenen Felder füllt. Weitere Relationen wie Ansprechpartner werden nicht gefüllt.

• GP_template.xml
  Dieses Template generiert Geschäftspartner mit basierender Person und Default-Ansprechpartner, hinzu kommt eine Straßenadresse und eine Telefonnummer.

• PRD_template.xml
  Dieses Template generiert Produkte inkl. deutscher Produktbeschreibung.

In allen Fällen ist darauf zu achten, dass die Quelldaten gültige Schlüssel aus dem Zielsystem enthalten. Beispielsweise muss Delegiert an/von mit einem gültigen Mitarbeiterkürzel gefüllt werden. Dasselbe gilt für den PersonenTyp (PersontypeKey), wo ein gültiger Schlüssel hinterlegt sein muss. Wurden die Schlüssel in den Beispieldaten überprüft (in der Regel die Felder, die mit Key enden), kann der Import mit den beigefügten Daten getestet werden.

Fachliche Beschreibung

Beim CURSOR-Importer handelt es sich um ein optionales Software-Program, welches separate Lizenzierung erfordert.

Der CURSOR-Importer ist eine Oberfläche für den Import von Daten aus CSV-Dateien oder Excel-Tabellen (im Folgenden 'Quelldatendatei' genannt). Mit dieser Oberfläche soll ein Anwender mit entsprechenden Vorkenntnissen den Datenimport einer definierten Datenstruktur selbständig durchführen können. Es sind keine tief greifenden Kenntnisse über das Datenmodell oder die Anwendung notwendig.

Um dem Anwender eine möglichst einfache Bedienung zu gewährleisten, gibt es XML-Vorlagen, wobei jede Vorlage den Import einer definierten Datenstruktur gewährleistet. Die Vorlagen werden von CURSOR Software AG bereitgestellt und sind in ihrem Funktionsumfang jeweils beschrieben.

Der Anwender bekommt eine Konfigurations- (*.xxic) sowie eine Vorlage-Datei (*.xml), die die Struktur der Quelldatendatei beschreibt. Mit dieser Konfiguration kann der Kunde mehrere Quelldatendateien derselben Struktur verarbeiten. Im ersten Schritt werden XML-Daten für die XML Import-Schnittstelle anhand von CSV- oder Excel-Tabellen generiert. Der CURSOR-Importer ermöglicht im zweiten Schritt einen direkten Import der Daten über die Webservice-Schnittstelle.

Im Importer erfolgt dann die Konfiguration, welche Information aus der Quelldatei in welche Information der Zieldatei erfolgen soll. Diese setzt voraus, dass die beiden Strukturen zueinander passen, sofern dies nicht der Fall ist, muss die Vorlagen angepasst werden.

Im Rahmen eines Importszenarios sind in der Regel weitergehende Prüfungen zu berücksichtigen. Hierzu zählen beispielsweise eine Dublettenprüfung oder eine Konsistenzprüfung der Daten, dies ist nicht Bestandteil des Importers, sondern ist mit separaten Tools bzw. Verfahren in dem Szenario zu berücksichtigen.

Features für Anwender

Bei der Verwendung des Tools wird empfohlen, die Vorgehensweise in zwei Schritte aufzuteilen:

1. Initiale Einrichtung mit CURSOR Software AG (Einstellungen der Import-Parameter)

2. Selbständige Durchführung des Imports

Die Einstellungen der Importparameter bleiben als Last-run-Einstellung in der Datei lastrun.properties erhalten. Für weitere Import-Vorgänge reicht es dann nur, die neue Quelldatendatei auszuwählen.

Im Folgenden sind alle Schritte beschrieben, die für die Verwendung des Tools notwendig sind, da die Einstellungen gespeichert werden, ist dies nur bei der initialer Konfiguration notwendig. Insbesondere bei den unter 'Einstellen des Webservice-Imports' beschriebenen Punkten sind spätere Änderungen in der Regel nicht notwendig.

Ein Projekt einrichten

Laden der Quelldatendatei

• Klicken Sie auf den Schalter Durchsuchen, um einen Suchdialog zu öffnen.

• Wählen Sie in dem Suchdialog Ihre Datei mit den zu importierenden Daten.

Auswählen der Tabelle (nur bei Excel-Dateien)

Falls Sie eine Excel-Datei gewählt haben, wird diese eingelesen. Wählen Sie im Auswahlfeld Tabelle die Tabelle, die die zu importierenden Daten enthält.

Einstellungen

Falls Sie eine CSV- oder Excel-Datei gewählt haben, können über den Schalter   Einstellungen   die in der Datei verwendeten Trenn- und Textbegrenzungszeichen sowie das Escape-Zeichen, der verwendete Zeichensatz (alles nur CSV) und ein Datumsformat gewählt werden. Wird der Dialog nicht geöffnet, werden die Werte vorbelegt. Meistens sind diese Einstellungen bereits korrekt. Über den Schalter   Standard   können die Standardeinstellungen wieder geladen werden.

Die Einstellungen müssen exakt der Kodierung in der Quelldatendatei entsprechen! Nur das Datumsformat ist optional, da die beiden Standardformate der XML-Import-Schnittstelle zusätzlich unterstützt werden.

CSV

Laden der Konfigurationsdatei

Sie haben von CURSOR Software AG eine Konfigurationsdatei (*.xxic) erhalten. Sie beschreibt die Struktur Ihrer Quelldatendatei.

• Klicken Sie auf den Schalter Durchsuchen, um einen Suchdialog zu öffnen.

• Wählen Sie in dem Dialog die Konfigurationsdatei.

Laden der Vorlagedatei

Sie haben von CURSOR Software AG eine Vorlagedatei (*.xml) erhalten, die als Vorlage für die zu generierenden Importanweisungen dient.

• Klicken Sie auf den Schalter Durchsuchen, um einen Suchdialog zu öffnen.

• Wählen Sie in dem Dialog die Vorlagedatei.

Wählen des Ausgabeordners

Die Importanweisungen müssen zum Durchführen des Importvorgangs in einem Verzeichnis abgelegt werden.

Wählen Sie möglichst ein leeres Verzeichnis aus oder legen Sie ein neues an.

Wählen des Präfix

Ausgabedateien werden nach dem Format <Mein Präfix>_0000000001.xml erzeugt. Das Präfix lässt sich hier frei wählen. Ausgeschlossen sind lediglich Zeichen, die im Dateisystem des Betriebssystems nicht erlaubt sind.

Einstellen der Offsets

Falls die zu importierenden Daten in der oben gewählten Datei versetzt sind (also nicht in Spalte 1, Zeile 1 beginnen), müssen die Offsets entsprechend angepasst werden. Ist die erste Zeile der Datendatei (oder Excel-Tabelle) eine Überschriftzeile, muss der vertikale Offset auf 1 gesetzt werden. (Im Beispiel unten beginnen die Daten für den Import ab Zeile 3, Spalte 1)

Einstellen des Webservice-Imports

• Falls kein direkter Import über den Webservice sondern nur XML-Ausgabe gewünscht wird, ist dieser Schritt zu überspringen. In diesem Fall werden die XML-Dateien in dem vordefinierten Ausgabeordner gespeichert.

• Beim Applikationsserver 'Websphere' kann das Tool ebenfalls genutzt werden, allerdings wird derzeit kein Webservice unterstützt.
  In diesem Fall ist die Option 'Import via Webservice' zu deaktivieren. stattdessen kann der XML-Ausgabeordner auf das überwachte Client-Verzeichnis gesetzt werden, um über den clientseitigen Import fortzufahren.

• Aktivieren Sie den Import via Webservice.

• Passen Sie die URL zum Webservice an ihren Server an. Die URL hat für gewöhnlich die Form:

http://<HOSTNAME>:<Portrange 1-5>8080/<PRODUKTNAME CARMEN/EVIJET/HELVIS>-ejb/WebServiceController

So kommt man an die Adresse des Webservices

• Tragen Sie die passenden Werte für Server, Portbereich und Produkt ein. Weitere Details zu Webservices entnehmen Sie der Dokumentation für Administratoren (Kapitel Webservices).

• Geben Sie einen Benutzernamen sowie das Passwort ein. Der Benutzer sollte in Ihrem System die Berechtigung haben, auf die Webservices zuzugreifen.

Testlauf und/oder Import

Der eigentliche Import erfolgt standardmäßig nach einem Testlauf. Sollte sich die Konfigurationsdatei als fehlerhaft erweisen, wird der Import nicht gestartet. Somit wird vermieden, dass die Daten nur teilweise importiert werden.

Funktionierte der Import fehlerfrei und liegt eine Excel-Tabelle gleicher Struktur vor, so kann der Testlauf übersprungen werden, um den Importvorgang zu beschleunigen.

Paketgröße

Der Parameter 'Paketgröße' gibt an, wie viele Datensätze maximal zu einer Importanweisung zusammengefasst werden sollen. Wird die Zahl überschritten, wird eine neue XML-Datei erstellt.

Es wird die standardmäßige Paketgröße 800 empfohlen. Wesentlich kleinere oder größere Werte können den Import verlangsamen.

Transaktionszeit

Die maximale Zeit, die der Import eines Paketes (NICHT der komplette Import) dauern darf, bevor er zurück gerollt wird, kann über 'Transaktionszeit' eingestellt werden. Die minimale Zeit sind 5 Minuten, die maximale 23 Stunden und 59 Minuten.

Stylesheet für Ergebnis verwenden

Statt mit

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

beginnen die Web Service Ergebnis-Dateien  nun mit

<?xml-stylesheet href="file:///<Laufwerk>:/<Pfad>/Standard.css" type="text/css"?>

Dadurch kann die Datei beispielsweise mit dem Browser geöffnet und formatiert eingesehen werden. Wird hierbei nur der Haken gesetzt zeigt der Pfad automatisch auf das im Importer-Ordner liegende Standard.css. Wird im Textfeld ein Stylesheet angegeben, wird dieser Pfad gesetzt.

Ausführen/Abbrechen des Importvorgangs

• Starten Sie den Importvorgang mit dem Schalter Starten.

• Zunächst werden die XML-Importanweisungen aus der Quelldatendatei im gewählten Ausgabeverzeichnis generiert. Üblicherweise wird diese Umwandlung nur einen kleinen Teil Zeit in Anspruch nehmen.

• Falls Import via Webservice gewählt wurde, wird im Anschluss eine Verbindung zum Webservice des CRM-Servers hergestellt und die Daten in einem Testlauf oder tatsächlichem Import importiert. Dieser Vorgang kann je nach Datenmenge einige Zeit in Anspruch nehmen.

• Der Vorgang kann über Abbrechen abgebrochen werden. Sofern noch die XML Dateien erstellt werden, wird direkt abgebrochen. Läuft bereits der WebService-Aufruf, wird erst nach dem nächsten Aufruf abgebrochen.

• Am unteren Rand wird angezeigt, wie viel Zeit noch bis zum eingetragenen Transaktionsende besteht.

Projekt sichern/laden

Im Projekt-Menü besteht die Möglichkeit, die getätigten Eingaben (also bspw. Quelldatendatei, Konfiguration, Offsets, Webservice-Einstellungen) abzuspeichern und zu einem späteren Zeitpunkt wiederherzustellen. Das ist sinnvoll, wenn Sie Excel-Tabellen und CSV-Dateien mit verschiedenen Strukturen importieren möchten. Die Importparameter werden in einer Projektdatei (*.xprj) gespeichert.

1. Zunächst Projekt speichern wählen.

2. Einen Speicherort wählen.

3. Später Projekt öffnen wählen.

4. Und die gespeicherte Datei auswählen.

Spaltenzuordnung

Die Konfigurationsdatei, die die Spalten der Quelldatendatei den Platzhaltern der Templatedatei zuordnet, kann im Tool selbst erstellt werden.

• Zunächst muss in der Oberfläche eine Quelldatendatei geladen worden sein (siehe Schritt Quelldatendatei laden).

• Über das Projekt-Menü wird die Spaltenzuordnungs-Eingabemaske aufgerufen.

Nun erscheint zunächst ein Dialog zum Eingeben eines Offsets. Der Vorschlagswert ist der im Hauptdialog eingestellte Offset. Dieser wird auch beim Klick auf Standard wieder eingestellt.

Der Unterschied zwischen den beiden Offsets

Der Offset im Hauptdialog muss auf den Beginn der Daten zeigen, die importiert werden sollen. Der hier verlangte Offset sollte dagegen auf die Werte zeigen, die besonders gut das Feld identifizieren. Wenn beispielsweise über den Daten eine weitere Zeile mit Überschriften vorhanden ist, bietet es sich, an den Offset auf diese Zeile zu setzen.

• Wenn zuvor eine Vorlagedatei ausgewählt wurde, ist diese bereits vorselektiert, andernfalls kann sie über

  Durchsuchen gewählt werden. Das Tool liest sie ein und listet die Platzhalter unter 'Vorlage-Schlüssel' auf.

• Die möglichen Spalten aus der Quelldatendatei stehen in den Auswahllisten unter "Datenspalte". Genutzt wird die Zeile am, beim Öffnen des Dialogs eingestellten, Offset der Quelldatendatei.

• Jedem Vorlage-Schlüssel wird eine Spalte der Quelldatendatei zugeordnet.

• Die Spaltenzuordnung muss gesichert werden (Sichern, *.xxic) und im Folgenden im Hauptfenster als Konfigurationsdatei geladen werden.

• Soll später etwas daran geändert werden, kann sie über Laden geladen und bearbeitet werden.

• Auswahl speichern erstellt eine Kopie der ausgewählten Vorlage. In dieser Kopie sind nicht alle Felder enthalten, sondern lediglich alle Felder, die in der Spalte Datenspalte zugeordnet wurden. Für den Fall, dass in der Quelldatei nicht immer dieselben Daten anliegen, sollte zunächst eine Vorlage mit der Obermenge aller Felder definiert werden. Im Anschluss kann anhand dieses Schalters schnell eine zu den vorhandenen Daten passende Vorlage erstellt werden.

• Zuordnen ordnet Vorlage-Schlüssel und die Werte aus der Auswahlliste automatisch einander zu, wenn sie gleich sind.

Suchen-/Ersetzenmuster

Durch das Angeben von regulären Ausdrücken können Werte aus der Quelldatei umformatiert werden, bevor sie in die XML-Struktur geschrieben werden. Die Syntax ist dabei:

<Mein Muster zum Suchen>,<Mein Muster zum ersetzen>

Beispiele:

MeinText,Text
^(\d{2})\.(\d{2})\.(\d{4})$,$3-$2-$1
NULL,
d[a-z]*d,MeinNeuerWert

Weiteres hierzu direkt in der Oracle Dokumentation: http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

Globalen Einstellungen

Im Projektmenü unter Globale Einstellungen können Einstellungen vorgenommen werden, die für alle Projekte gelten.

Logpfad

Es kann das Verzeichnis gewählt werden, in das geloggt wird. Standardmäßig ist das das Verzeichnis des Importers selbst.

Log-Dateien

Der CURSOR-Importer loggt in verschiedene Dateien. Alle Arten von Dateien (weiter unten beschrieben) legen, sofern sie eine gewisse Größe erreichen, eine neue Datei an. Alte Dateien bleiben erhalten bis eine gewisse Anzahl an Dateien vorhanden ist, dann wird die älteste wieder überschrieben.

• errors.log

Hier werden echte Fehler geloggt. Z.B. wenn der Server nicht läuft, ein Programmfehler auftritt und das falsche Encoding für die Quelldatei angegeben wurde. Dies sollte die erste Anlaufstelle sein, wenn der WebService nicht aufgerufen werden konnte. Der Haken 'Fehler im Logdialog anzeigen' bestimmt, ob diese Datei geladen und im Logdialog angezeigt wird.

• warnings.log

Hier werden Hinweise geloggt. Z.B. wenn die lastrun.properties nicht gefunden wurde. Dies ist kein Fehler, da dann die Standardwerte genutzt werden. Normalerweise wird diese Datei für den Anwender nicht von Interesse sein. Der Haken 'Warnungen im Logdialog anzeigen' bestimmt, ob diese Datei geladen und im Logdialog angezeigt wird.

• progress.log

Hier werden alle Tätigkeiten des Importers protokolliert. Beispielsweise das Ersetzen der Variablen, das Einlesen der Werte etc. Normalerweise wird diese Datei für den Anwender nicht von Interesse sein. Der Haken 'Fortschritt im Logdialog anzeigen' bestimmt, ob diese Datei geladen und im Logdialog angezeigt wird.

• webservice_input.log

Hier wird der XML-Code geloggt, der an den WebService gesendet wird. Der Haken 'WebService-Eingabe im Logdialog anzeigen' bestimmt, ob diese Datei geladen und im Logdialog angezeigt wird.

• webservice_output.log

Hier wird der XML-Code geloggt, der vom WebService zurück kommt. Dies sollte die erste Anlaufstelle sein, wenn der Server bzw. der WebService erreicht wurde, aber nicht das gewünschte Ergebnis erzielt wurde. Der Haken 'WebService-Ausgabe im Logdialog anzeigen' bestimmt, ob diese Datei geladen und im Logdialog angezeigt wird.

Anzahl der Dateien zum Laden

Unter 'Log-Dateien' wurde bereits beschrieben, dass von jeder Art Datei noch alte Versionen existieren können. Mit 'Lade nur die neueste Logdatei' wird festgelegt, ob diese beim Öffnen des Logdialogs ebenfalls geladen werden. Dies kann das Öffnen des Dialogs um längere Zeit verzögern.

Rückgabedialog anzeigen

Wenn der WebService erreicht, in der XML-Struktur aber ein Fehler erkannt wurde, wird die zurückgegebene XML Struktur ein einem Dialog angezeigt. Dies kann mit der Option 'WebService Rückgabe verarbeiten' ausgeschaltet werden.

Rückgabedialog

Wenn der WebService erreicht, in der XML-Struktur aber ein Fehler erkannt wurde, wird die zurückgegebene XML Struktur ein einem Dialog angezeigt.

• In dem Baum auf der linken Seite können die einzelnen Datensätze ausgewählt werden.

  • Auf der rechten Seite werden nun die darin enthaltenen Fehler angezeigt.

• Über die Option 'Nur Fehler anzeigen' werden die Datensätze herausgefiltert, die einen Fehler gemeldet haben.

Logdialog

Über den Schalter Logdateien einsehen kann der Inhalt aller über die globalen Einstellungen konfigurierter Dateien eingesehen werden.

Über die Tastenkombination STRG+F  kann auf den Laschen ein Suchfenster geöffnet werden.

Batch-Betrieb

Der CURSOR-Importer ermöglicht den Betrieb im Batch-Modus. Hierbei wird die grafische Benutzeroberfläche (GUI) nicht benutzt, stattdessen werden die Einstellungen per Kommandozeilenparameter übergeben und der Importvorgang sofort gestartet. Folgende Parameter sind verfügbar:

Um die Bedienhinweise zu sehen, kann die Klasse de.cursor.importer.console.ConsoleImporter ohne Parameter aufgerufen werden:

Ein Importbefehl könnte also beispielsweise so aussehen (zur Verbesserung der Lesbarkeit wird der Befehl umgebrochen):

EXCEL

$java -cp importer.jar de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Excelbeispiel\config.xxic -s Tabelle1 -d d:\ImporterBeispiele\Ausgabe
-f d:\ImporterBeispiele\Excelbeispiel\acts.xlsx -t d:\ImporterBeispiele\Excelbeispiel\template.xml
-v 1 -w both --webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController
--webservice-password 7FC203845F060800D0CA152D46BA8269 --webservice-user bne
 
 
Mit SSL (ab 19.2 zwingen nötig):
$java -cp importer.jar -Djavax.net.ssl.trustStore="mytruststore.p12" -Djavax.net.ssl.trustStorePassword="mytruststorepw" de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Excelbeispiel\config.xxic -s Tabelle1 -d d:\ImporterBeispiele\Ausgabe
-f d:\ImporterBeispiele\Excelbeispiel\acts.xlsx -t d:\ImporterBeispiele\Excelbeispiel\template.xml
-v 1 -w both --webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController
--webservice-password 7FC203845F060800D0CA152D46BA8269 --webservice-user bne


Ab 21.1.1:
$java -cp lib/importer.jar -Djavax.net.ssl.trustStore="mytruststore.p12" -Djavax.net.ssl.trustStorePassword="mytruststorepw" de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Excelbeispiel\config.xxic -s Tabelle1 -d d:\ImporterBeispiele\Ausgabe
-f d:\ImporterBeispiele\Excelbeispiel\acts.xlsx -t d:\ImporterBeispiele\Excelbeispiel\template.xml
-v 1 -w both --webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController
--webservice-password 7FC203845F060800D0CA152D46BA8269 --webservice-user bne

CSV

$java -cp importer.jar de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Aktivitäten\act_conf.xxic -t d:\ImporterBeispiele\Aktivitäten\ACT_template.xml
-d d:\ImporterBeispiele\Ausgabe -f d:\ImporterBeispiele\Aktivitäten\act_import.csv -v 1 -w both
--webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController --webservice-password 7FC203845F060800D0CA152D46BA8269
--webservice-user bne -e windows-1252 -es \ -sep ; -q \" -df dd.MM.yyyy
 
 
Mit SSL (ab 19.2 zwingen nötig):
$java -cp importer.jar -Djavax.net.ssl.trustStore="mytruststore.p12" -Djavax.net.ssl.trustStorePassword="mytruststorepw" de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Aktivitäten\act_conf.xxic -t d:\ImporterBeispiele\Aktivitäten\ACT_template.xml
-d d:\ImporterBeispiele\Ausgabe -f d:\ImporterBeispiele\Aktivitäten\act_import.csv -v 1 -w both
--webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController --webservice-password 7FC203845F060800D0CA152D46BA8269
--webservice-user bne -e windows-1252 -es \ -sep ; -q \" -df dd.MM.yyyy


Ab 21.1.1:
$java -cp lib/importer.jar -Djavax.net.ssl.trustStore="mytruststore.p12" -Djavax.net.ssl.trustStorePassword="mytruststorepw" de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Aktivitäten\act_conf.xxic -t d:\ImporterBeispiele\Aktivitäten\ACT_template.xml
-d d:\ImporterBeispiele\Ausgabe -f d:\ImporterBeispiele\Aktivitäten\act_import.csv -v 1 -w both
--webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController --webservice-password 7FC203845F060800D0CA152D46BA8269
--webservice-user bne -e windows-1252 -es \ -sep ; -q \" -df dd.MM.yyyy

Und so wäre das Ergebnis:

Zum Generieren des Passwort-Hashs nutzen Sie:

CODE

$ java -cp importer.jar de.cursor.importer.helper.PasswordStorage <Passwort>

Technische Dokumentation

Vorgehensweise zur Erstellung eines neuen Projektes

Hat man noch keine Konfigurationsdatei für eine vorhandene Vorlage, mit der man eine vorhandene Quelldatei importieren will, so ist wie folgt vorzugehen:

1. Die Quelldatendatei auswählen

2. Den Menüpunkt Projekt/Spaltenzuordnung wählen

3. Im Konfigurationsdialog die Vorlagedatei auswählen

4. Das Mapping entsprechend konfigurieren

5. Mit einem Klick auf den Schalter Spaltenzuordnung sichern die Konfigurationsdatei erstellen

Wurde in der Quelldatei über der ersten Datenzeile eine Zeile mit Überschriften eingefügt, kann es hilfreich sein den Offset vor dem Öffnen des Konfigurationsdialogs auf die Zeile mit den Überschriften zu setzen. Dadurch wird bei sprechenden Überschriften das Zuordnen erleichtert.

Erstellung der Konfigurations- und Templatedateien

Schritt 1

Zuerst wird eine beispielhafte template.xml-Datei entsprechend des XML-Import-Schemas angelegt. Die Datei enthält nur ein einzelnes <Entry>-Tag, keine XML-Deklaration und kein <Entries>-Root-Tag.

Die Datei muss UTF-8-Kodierung besitzen, eine Byte-Order-Mark darf nicht vorkommen.

Beispiel:

 <Entry entity="Customer" action="UPDATE_OR_CREATE" found="ONE">
<Field name="MatchCode.Customer" identifyingField="true">
<FieldValue>
<stringValue>HELABA BANK</stringValue>
</FieldValue>
</Field>
 
<Field name="Name1.Customer" identifyingField="false">
<FieldValue>
<stringValue>Landesbank Hessen-Thüringen</stringValue>
</FieldValue>
</Field>
 
<Field name="Name2.Customer" identifyingField="false">
<FieldValue>
<stringValue>AG</stringValue>
</FieldValue>
</Field>
 
<Field name="Name3.Customer" identifyingField="false">
<FieldValue>
<stringValue />
</FieldValue>
</Field>
 
<Field name="PeAddressType.Customer" identifyingField="false">
<FieldValue>
<stringValue>STRASSE</stringValue>
</FieldValue>
</Field>
 
<Field name="PeStreet.Customer" identifyingField="false">
<FieldValue>
<stringValue>Ständeplatz</stringValue>
</FieldValue>
</Field>
 
<Field name="PeStreetNumber.Customer" identifyingField="false">
<FieldValue>
<stringValue>17</stringValue>
</FieldValue>
</Field>
 
<Field name="PeCity.Customer" identifyingField="false">
<FieldValue>
<stringValue>Offenbach</stringValue>
</FieldValue>
</Field>
 
<Field name="PeZIP.Customer" identifyingField="false">
<FieldValue>
<stringValue>34117</stringValue>
</FieldValue>
</Field>
 
<Field name="PhoneNoCountry.Customer" identifyingField="false">
<FieldValue>
<stringValue>+49</stringValue>
</FieldValue>
</Field>
 
<Field name="PhoneNoCity.Customer" identifyingField="false">
<FieldValue>
<stringValue>069</stringValue>
</FieldValue>
</Field>
 
<Field name="PhoneNoBase.Customer" identifyingField="false">
<FieldValue>
<stringValue>9132</stringValue>
</FieldValue>
</Field>
 
<Field name="PhoneNoExtension.Customer" identifyingField="false">
<FieldValue>
<stringValue>01</stringValue>
</FieldValue>
</Field>
 
<Field name="CustTypeKey.Customer" identifyingField="false">
<FieldValue>
<stringValue>KEINE BEZIEHUNG</stringValue>
</FieldValue>
</Field>
 
<Field name="EmployeeOffice.Customer" identifyingField="false">
<FieldValue>
<stringValue>ALA</stringValue>
</FieldValue>
</Field>
 
<Field name="EmployeeSales.Customer" identifyingField="false">
<FieldValue>
<stringValue>THR</stringValue>
</FieldValue>
</Field>
</Entry>

Schritt 2

Die Werte der Felder der o.g. Templatedatei, die beim Import von der Quelldatendatei gespeist werden sollen, werden durch beliebige Platzhalter ersetzt. Platzhalter haben die Form @$<Platzhalterbezeichner>$@. Die Platzhalter sind zunächst unabhängig von der Reihenfolge der Spalten in der Quelldatendatei.

Beispiel:

 <Field name="Name1.Customer" identifyingField="false">
<FieldValue>
<stringValue>@$CustomerName$@</stringValue>
</FieldValue>
</Field>
<Field name="PhoneNoBase.Customer" identifyingField="false">
<FieldValue>
<stringValue>@$PhoneBase$@</stringValue>
</FieldValue>
</Field>

Felder, die beim Import einen festen Wert zugewiesen bekommen sollen, bleiben unberührt.

Schritt 3

Nun wird eine Konfigurationsdatei config.xxic angelegt, die die Spalten der Quelldatendatei einem Platzhalter in der Templatedatei zuweist. Dies kann programmgesteuert erfolgen, wie manuell im Folgenden erläutert.

Die Datei ist wie folgt aufgebaut:

• jede Zeile enthält eine Zuweisung: <Schlüssel>=<Wert> beginnend mit dem Schlüssel 0.

• Pflichtschlüssel: template muss den Pfad zur oben erstellten Templatedatei angeben (ggf. relativ zur Konfigurationsdatei selbst)

• Jedem Spaltenindex der Quelldatendatei wird ein Platzhalter zugewiesen: <Spaltenindex>=<Platzhalterbezeichner>

• Zusätzlich kann jeder Spalte eine Prozessor-Klasse zugewiesen werden, die praktisch beliebige Prüfungen und Veränderungen der Werte möglich macht. Diese Veränderungen greifen allerdings erst nach dem Einlesen eines Wertes. Ein Datumswert beispielsweise kann nicht hierüber verändert werden, so dass er dann auf das angegebene Datumsformat passt.
  <Spaltenindex>.processors=<Klasse1>;<Klasse2>(<Arg1>,<Arg2>);..;<KlasseN>

  • Mögliche Prozessor-Klassen sind derzeit:

    1. NotEmpty -- Meldet einen Fehler wenn ein Feld der Spalte leer ist

    2. Regex -- Führt ein Suchen/Ersetzen mittels Regulärer Ausdrücke in jedem Feld dieser Spalte durch (siehe folgendes Beispiel)

    3. IsFloat -- Meldet einen Fehler wenn der Wert in der Spalte kein Float ist

    4. IsInt -- Meldet einen Fehler wenn der Wert in der Spalte kein Int ist

Beispiel:

template=template.xml
0=CustomerName
1=PhoneBase
2=Date
2.processors=NotEmpty;Regex(^(\\d{2})\\.(\\d{2})\\.(\\d{4})$,$3-$2-$1)

Dies hätte zur Folge, dass in der dritten Spalte (Date) keine leeren Werte erlaubt werden, und Werte der Form DD.MM.YYYY nach YYYY-MM-DD konvertiert werden.

Besonderheiten bei der Zahl und Datumsformatierung

Excel

Zahl- und Datumswerte aus Excel werden nicht so in die XML-Struktur übertragen, wie in Excel angegeben, sondern es wird versucht, sie dem im Template angegebenen Typ anzupassen. Bei Zahlen mit <intValue></intValue> würden beispielsweise Nachkommastellen abgeschnitten, während sie bei <doubleValue></doubleValue> oder <longValue></longValue> übernommen, bzw. mit Nullen aufgefüllt würden. Bei Datumswerten wird jeweils in Datum mit/ohne Zeit umgewandelt. Im Folgenden wird jeweils aufgelistet bei welchen Excelformatierungen dies korrekt funktioniert.

Alle hier nicht aufgelisteten Formatierungen werden nicht unterstützt.

Unterstütze Zahlformate

In allen Fällen werden sowohl Punkt als auch Komma als Vor-/Nachkommatrenner unterstützt.

• Zahlen können als Standard formatiert werden.

• Zahlen können als Text formatiert sein.

• Sind die Zahlen als Zahl formatiert, dürfen sämtliche Einstellungsmöglichkeiten genutzt werden.

Endet eine Zahl mit ".0" und das Ziel ist ein <stringValue>, wird das ".0" abgeschnitten.

Unterstütze Datumsformate

• Ist ein Datum als Datum formatiert, können alle deutschen und englischen (Großbritannien) Formatierungen genutzt werden.

• Hat ein Datum bereits die richtige Struktur für die Schnittstelle, also 1983-07-05T00:00:00 oder 1983-07-05, darf es auch als Standard oder Text formatiert sein. In diesem Fall wird allerdings nur zwischen diesen beiden Formaten hin und her formatiert, alle anderen Formate funktionieren hier nicht.

Zusätzlich wird pro Excel-Datei ein beliebiges anderes Format unterstützt. Nach dem Laden einer Excel-Datei kann über den Schalter Einstellungen ein Dialog geöffnet werden, in dem dieses Format angegeben werden kann. Dieses greift nur, wenn keines der beiden Standardformate erkannt wurde.

Mögliche Datumskonfigurationen

Beispiele: "yyyy.MM.dd G HH:mm:ss z", "EEE, MMM d, yy", "h:mm a", "K:mm a, z", "yyyyy.MMMMM.dd GGG hh:mm aaa", "EEE, d MMM yyyy HH:mm:ss Z", "yyMMddHHmmssZ"

CSV

Bei Zahl- und Datumswerten aus CSV wird versucht, sie dem im Template angegebenen Typ anzupassen. Bei Zahlen mit <intValue></intValue> würden beispielsweise Nachkommastellen abgeschnitten, während sie bei <doubleValue></doubleValue> oder <longValue></longValue> übernommen, bzw. mit Nullen aufgefüllt würden. Bei Datumswerten wird jeweils in Datum mit/ohne Zeit umgewandelt. Im Folgenden wird jeweils aufgelistet, bei welchen Formatierungen dies korrekt funktioniert.

Unterstütze Zahlformate

Zahlen können ganzzahlig, mit Punkt oder Komma getrennt angegeben werden.

Unterstütze Datumsformate

Datumswerte können in den beiden standard XML-Import-Formaten angegeben werden. Es wird immer zunächst darauf geprüft.

Zusätzlich wird pro CSV-Datei ein beliebiges anderes Format unterstützt. Nach dem Laden einer CSV-Datei kann über den Schalter 

Mögliche Datumskonfigurationen

Beispiele: "yyyy.MM.dd G HH:mm:ss z", "EEE, MMM d, yy", "h:mm a", "K:mm a, z", "yyyyy.MMMMM.dd GGG hh:mm aaa", "EEE, d MMM yyyy HH:mm:ss Z", "yyMMddHHmmssZ"

Automatisches Füllen mit dem Leerschlüssel

Soll ein Import über den CURSOR-Importer oder direkt über die XML-Import-Schnittstelle durchgeführt werden, und ein Nachschlagefeld, auf dem der Leerschlüssel erlaubt ist, wird nicht gefüllt (siehe folgende Beispiele), so wird es nun automatisch mit dem Leerschlüssel vorbelegt. Diese Änderungen greifen für die Versionen 12.1, 11.2.01 und 11.1.14.

Beispiel Excel:

Beispiel CSV:

Beispiel XML:

Leeren von Boolean, Double, Date

Soll ein Import über den CURSOR-Importer durchgeführt werden, und ein Datum, Zahl oder Booleanfeld wird nicht gefüllt (siehe folgende Beispiele), so wird es nun geleert.

Beispiel Excel

Excel-Fehler: Unerwartete Zeichen im Text

Wird in einer xlsx-Datei in einer Zelle mehrzeiliger Text hinterlegt, kann es dazu kommen, dass in den generierten XML-Dateien und somit auch in den importierten Datensätzen an der Stelle des Zeilenumbruchs unerwartete Zeichen auftauchen. Beispielsweise "_x000D_". Dies ist ein Bug von Excel, auf den CURSOR Software AG keinen Einfluss hat. Als Workaround kann die xlsx-Datei als xls-Datei abgespeichert und neu vom Importer eingelesen werden. Dadurch wird das Problem umgangen.

$java -cp importer.jar de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Aktivitäten\act_conf.xxic -t d:\ImporterBeispiele\Aktivitäten\ACT_template.xml
-d d:\ImporterBeispiele\Ausgabe -f d:\ImporterBeispiele\Aktivitäten\act_import.csv -v 1 -w both
--webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController --webservice-password 7FC203845F060800D0CA152D46BA8269
--webservice-user bne -e windows-1252 -es \ -sep ; -q \" -df dd.MM.yyyy
 
 
Mit SSL (ab 19.2 zwingen nötig):
$java -cp importer.jar -Djavax.net.ssl.trustStore="mytruststore.p12" -Djavax.net.ssl.trustStorePassword="mytruststorepw" de.cursor.importer.console.ConsoleImporter
-c d:\ImporterBeispiele\Aktivitäten\act_conf.xxic -t d:\ImporterBeispiele\Aktivitäten\ACT_template.xml
-d d:\ImporterBeispiele\Ausgabe -f d:\ImporterBeispiele\Aktivitäten\act_import.csv -v 1 -w both
--webservice-url http://localhost:18080/CARMEN-ejb/WebServiceController --webservice-password 7FC203845F060800D0CA152D46BA8269
--webservice-user bne -e windows-1252 -es \ -sep ; -q \" -df dd.MM.yyyy