IDU.GeoTools.Net

PuzzleImport / ToPuzzle

  • Die Datensätze werden per XML-Austauschformat in ein cardo.Puzzle-Dokument umgewandelt und zum cardo-Server (PuzzleBaseService2-Webdienst) geschickt
  • Dazu werden die Quell- und Ziel-Schemata abgerufen und anhand von Namen und Datentyp verglichen

    Damit die automatische Zuordnung funktioniert, müssen die Daten-Strukturen übereinstimmen!

  • Ggf. muss vorher eine Aufbereitung der Quell-Daten per Abfrage (Parameter 'query') erfolgen, sodass die Spaltennamen übereinstimmen oder die passenden Spaltennamen per Parameter an das Programm übergeben
  • Wenn Dokumente bereits vorhanden sind (Vergleich der UUID), werden die Daten dort eingefügt, bzw. überschrieben
    • Ist das Dokument nicht vorhanden, wird dieses angelegt
  • Listen und komplexe, nicht-geschachtelte Entities (Datentyp 'Unterklasse') können jetzt als JSON-formatierte Spalte übergeben werden ( siehe Details)

Achtung: Aktuell werden Nachschlagelisten noch nicht unterstützt!

Programmablauf

  1. Auslesen von Namen und Datentypen der Spalten
    1. Datenquelle
      • Spalten-Namen werden aus dem SQL-Statement übernommen, können also per AS beliebig umbenannt werden
      • die Daten-Typen werden aus den Spalten-Definitionen der abgefragten Tabelle ausgelesen
    2. aus Puzzle
      • hier wird die entsprechende DescribeClass-Funktion aufgerufen
  2. Vergleich und Auswertung der Spalten (matching)
  • siehe Log-Ausgaben (pro Spalte, Umfang der Infos je nach Loglevel)
  • der optionale Parameter matchingBehaviorIsStrict entscheidet über Abbruch mit Fehlermeldung oder 'nur' Warnungs-Text
    • ebenfalls ist der Parameter mit dem Wert false bei Beziehungsklassen obligatorisch, da die einzelnen Eigenschaften per JSON übertragen werden und desshalb keine 1:1-Zuordnung der einzelnen Eigenschaften/Felder möglich ist

    Bei komplexen Typen wie den Nachschlageklassen und den Beziehungsklassen erfolgt immer eine Warnung, weil deren Struktur nicht validiert werden kann

  1. Ausgabe der Exchange-XML-Dateien in den Ausgabeordner
  • die Anzahl der generierten XML-Dateien richtet sich natürlich nach Anzahl und Umfang der Quell-Daten
    • damit auch umfangreiche Datensätze per XML über die Web-Schnittstelle übertragen werden können, lassen sich die Datensätze pro Datei mit dem Parameter xmlRecordsPerFile limieren
  • änderbar über den Parameter puzzleOutputFolder
  1. Upload der XML-Dateien
  • jedes Dokument wird der Webdienst-Funktion ImportExchangeDocument übergeben
  • dessen "Feedback" wird ebenfalls im Ausgabeordner abgelegt (für detaillierte Fehler-Analysen)

Hinweise für das Einsortieren der Dokumente in Ordner

  1. Verhalten des Tools, wenn..
  • beides angegeben wurde, werden diese ohne Überprüfung an Puzzle übergeben (siehe 2.)
  • beides nicht angegeben wurde, werden die Dokumente im Root/Stammverzeichnis angelegt
  • nur [UUID] angegeben wurde, wird versucht das zugehörige [LABEL] aus Puzzle abzufragen, sonst Fehler
  • nur [LABEL] angegeben wurde, wird versucht die zugehörige [UUID] aus Puzzle abzufragen. Alternativ wird eine neue [UUID] generiert
  1. Verhalten von Puzzle, wenn..
  • [UUID] noch nicht vorhanden, wird der Ordner mit dem Namen in [LABEL] angelegt
  • [UUID] bereits vorhanden, wird [LABEL] ignoriert
  • [LABEL] nicht vorhanden, kommt ein (XML-Schema-)Fehler zurück

Hinweise für die JSON-Notation um Listen / Unterklassen-Datentypen übergeben zu können

  1. Das JSON darf nicht als reines Array von Objekten formatiert sein, sondern als Objekt mit einem Dummy-Eigenschaftsnamen und dem Array als Wert
  • Bsp. für string-Array:
    {"strings" : ["a", "b"]}
    
  • Bsp. für komplexes Objekt:
    {"complex_object" : [{"property1" : "value1", "porperty2" : "value2"}}]}"
    

Hinweise für die Abfrage der Datenquelle

  • Man kann entweder eine nahezu unveränderte Datenquelle importieren, indem man die passenden Parameter für die Angabe der Spaltennamen beim Aufruf des Tools angibt
    • hat den Vorteil, dass wenn die Puzzle-Kategorie Validierungen/Plausibilisierungen durchführt, diese auch wie gedacht funktionieren können, da sie auf den Original-Eigenschaftsnamen zugreifen
  • Beispiel-Szenarien, wo das Aufbereiten der Quelledaten per SQL sinnvoll ist:
    • bei einfachen Kategorien
    • um die Aufruf-Parameter übersichtlich zu halten
    • bei Datenquellen, die semantisch/inhaltlich vorher aufbereitet werden müssen
    • bei 1:n-Beziehungen müssen entsprechende Joins/Sub-Selects als JSON formatiert werden

SQL-Beispiele

Dieses Beispiel zeigt eine Abfrage für 1 Datensatz mit n Objekten vom fiktiven Typ "Ansprechpartner", welcher die Eigenschaften "NAME" und "TELEFON" bündelt, wobei "TELEFON" wiederum mehrfach vorkommen kann (also als Array/Liste erzeugt wird)

SELECT 
    *,
    NOW()                                   AS DATUM,
    'PuzzleImport'                          AS NUTZER,
    json_build_object('complex_object', 
        json_build_array(
            json_build_object('NAME', column_name, 'TELEFON', json_build_array(column_telefon)),
            json_build_object('NAME', column_name_2, 'TELEFON',  json_build_array(column_telefon_2)),
            json_build_object('NAME', column_name_3, 'TELEFON',  json_build_array(column_telefon_3))
        ))                                  AS LISTE_KOMPLEXER_OBJEKTE

FROM demodaten.test
GROUP BY pk_id;

Beispiel-Ausruf der Funktion aus einer Batch-Datei

ToPuzzle from:%SOURCE_ALIAS% cardoSrv:"http://localhost:90" ikxStoreID:0 puzzleCategoryID:"CAT_ID_TEST" puzzleUuidColumn:"uuid" puzzleNameColumn:"name" puzzleGeomColumn:"geom" matchingBehaviorIsStrict:false

XML-Beispiel-Snippet einer vom Tool generierten Ausgabe-Datei

<KOMPLEXER_TYP_List>
    <KOMPLEXER_TYP sortHint="0" uuid="_uuid_0">
        <NAME>Frau Mustermann</AP_NAME>
        <TELEFON_List>
            <TELEFON sortHint="0">0815</AP_TELEFON>
            <TELEFON sortHint="0">0816</AP_TELEFON>
        </TELEFON_List>
    </KOMPLEXER_TYP>
    <KOMPLEXER_TYP sortHint="1" uuid="_uuid_1">
        <NAME>Herr Mustermann</AP_NAME>
        <TELEFON_List>
            <TELEFON sortHint="0">0817</AP_TELEFON>
        </TELEFON_List>
    </KOMPLEXER_TYP>
</KOMPLEXER_TYP_List>

Auflistung aller Argumente

Diese Auflistung wurde durch den Befehl help ToPuzzle in der Eingabeaufforderung des GeoTools erzeugt.

Argument Beschreibung
from Name der per 'Connect'-Befehl verbundenen Daten-Quelle
query (Optional) GeoSQL-Abfrage zum Filtern oder Aufbereiten der Daten
cardoSrv Url zum cardo (http://meinCardo:90)
cardoUser (Optional) Benutzername für cardo (wenn leer, dann NT)
cardoPwd (Optional) Kennwort zu srvUser
ikxStoreID (Optional) numerische ID des cardo.Puzzle-Datenspeichers (siehe cardo3-Managementcenter für Ikx -> Tab 'Store-Name' -> Info -> ID, Standard: 0
puzzleCategoryID Alphanumerische ID der cardo.Puzzle-Kategorie (siehe cardo3-Managementcenter für Ikx -> Tab 'Store-Name' -> Tab 'cardo Puzzle' -> Verwaltungsdaten -> ClassID
puzzleUuidColumn (Optional) Name der Datenspalte aus Quelle für die Puzzle-UUID, Standard: 'pzl_node_id'
puzzleNameColumn (Optional) Name der Datenspalte aus Quelle für den Puzzle-Dokumenten-Namen, Standard: 'plz_node_title'
puzzlePathUuidColumn (Optional) Name der Datenspalte aus Quelle für die UUID des übergeordneten Ordners, Standard: 'plz_node_path_uuid'
puzzlePathLabelColumn (Optional) Name der Datenspalte aus Quelle für den Anzeigenamen des übergeordneten Ordners, Standard: 'plz_node_path_label'
puzzleGeomColumn (Optional) Name der Datenspalte aus Quelle für die IXK-Standardklassen-Geometrie, Standard: 'base_geom'
puzzleDescColumn (Optional) Name der Datenspalte aus Quelle für die Beschreibung, Standard: 'base_desc'
puzzleOutputFolder (Optional) Absoluter oder relativer (zur .exe) Pfad der Ausgabe-Dateien (Generierte XML-Dateien und Feedback vom cardo-Webservice), Standard: 'ToPuzzle_temp'
matchingBehaviorIsStrict (Optional) Gibt an, ob das Matching der Spalten streng beurteilt wird und jede Abweichung somit zum Fehler führt oder bei 'false' nur als Warnung ausgegeben wird, Standard: 'true'
xmlRecordsPerFile (Optional) Gibt an, wie viele Datensätzte in einer XML-Datei zusammengefasst werden (bei vielen kleinen Datensätzen in eine größere Zahl performanter, bei umfangreichen Datensätzen ist eine kleine Zahl zu empfehlen), Standard: '10'

Zuletzt geändert: 13.03.2024 12:40:13 (erstmals erstellt 08.02.2019)