Allgemein

Antony stellt eine Möglichkeit bereit Daten kontinuierlich von externen Quellen in Kontakte und Flexobjekte zu importieren. Die Quelle wird dabei von einem einfachen, ausführbaren Programm ausgelesen und das Ergebnis in antony importiert. Dieses Programm nennen wir Importer. Als Schlussfolgerung können von allen Quellen importiert werden, welche von einem Programm abgerufen werden können. Sei es eine Datenbankverbindung, REST-APIs, Dateien im Dateisystem, per FTP oder sonstiges.

Einzige und wichtigste Voraussetzung ist, dass das Fremdsystem eine konsistente ID liefert. Wenn diese nicht vorhanden ist, so können importierte Objekte nicht mehr geändert, sondern nur neue hinzugefügt werden.

Die Daten vom Importer werden angenommen und anschließend über ein Mapping auf die Felder in antony gemapped. Dieser Prozess findet zum Entlasten der AntonyDienste im Importer selbst statt. antony bietet für die einfache Implementierung ein NuGet Paket (antony.Groupware.DataImport 2.22.31.6 ) an.

Technische Funktionsweise

Die folgende Abbildung beschreibt die Funktionsweise. In der Mitte ist der antony-Server zu sehen. Die Datenquelle, welche anzusprechen ist, ist als Datenbank auf der rechten Seite zu sehen.

Die Antony-Dienste beinhalten ein AntonyImportModul welches sich im Mainservice befindet. Dieses führt den Importer in einem einstellbaren Zeitinterval aus. Der Importer liest die Daten aus der Datenquelle aus, mappt diese nach Konfiguration und übergibt sie zurück an das AntonyImportModul. Schlussendlich werden die zurückgegebenen “Anweisungen” vom AntonyImportModul ausgeführt und entsprechend importiert.

Das AntonyImportModule wird während der Umbauten auf die neue Struktur zwischen den neuen Diensten wandern. Die Einstellungen bleiben allerdings identisch

Schnittstelle zwischen AntonyImportModul und Importer

Die Schnittstelle zwischen dem AntonyImportModul und dem Importer arbeitet dateibasiert, um eine möglichst große Kompatibiliät zu erreichen. Das AntonyImportModule erzeugt bei einem Import zwei relevante Dateien. Wir empfehlen eine .NET Anwendung mit dem NuGet Paket für den Import zu verwenden. Anschließend wird der konfigurierte Importer mit den beiden Dateien gestartet. Als Ergebnis liefert der Importer wieder eine Datei, welche anschließend verarbeitet wird.

importconfig.json

Diese Datei enthält die Konfiguration des Imports. Unten findet sich ein gekürztes Beispiel. Zunächst enthält diese ein paar Metadaten. Interessant hierbei sind die ConnectionInformation, welche in diesen Fall einen Connectionstring enthält. Es könnte sich aber allerdings auch um Zugangsdaten für eine REST-Schnittstelle oder sonstiges handeln. Die Belegung vom Importer abhängig.

Ebenfalls kann der Importer einen weiteren Parameter enthalten, welcher im ImportParameter stehen. Für einen generischen MySqlImporter könnte dort beispielsweise einen SQL-Abfrage stehen. Der Parameter ImportGroup wird weiter unten erläutert

{
  "ImportId": "94696bad-379f-43ed-bcf7-07ff5a135df8",
  "Frequency": "00:01:00",
  "Comment": "BPS-Projekt",
  "ConnectionInformation": "User=root;Pwd=password;Host=127.0.0.1;Port=3306;Driver ...",
  "ImportParameter": "",
  "ImportGroup": "TestGruppe",
  "MappingName": "TestKontakte",
  "Configurations": [
    {
      "ForeignSourceField": "FIRST_NAME_FIELD_OF_FOREIGN_SYSTEM",
      "AntonyTargetField": "Firstname",    
    }, {
      "ForeignSourceField": "SOME_CUSTOM_FIELD_OF_FOREIGN_SYSTEM",
      "AntonyTargetField": "Field_4711",
      "ConverterInfos": [
        {
          "ConverterName":"Expression",
          "ConverterParameter":"(t) => { 
            var match = new System.Text.RegularExpressions.Regex(\"(?<str>[^,]+),[ ]*(?<plz>[^ ]+)[ ]+(?<ort>.*)\").Match(t.ToString()); 
            if (!match.Success) 
              return $\"(Nicht erkannt) {t}\"; return match.Groups[\"str\"].Value; 
              }"
        }
    }
  ]
}

Unter den Metadaten befinden sich Informationen zum eigentlichen Mapping. Diese werden im AntonyImportModul konfiguriert und beschreiben das Mapping der Felder aus dem Fremdsystem und antony. Die Einträge enthalten immer ein ForeignSourceField und ein AntonyTargetField. Entsprechend dieser Mappings ist die Ausgabedatei zu generieren.

Die Konverter bereiten dem Import eine gewisse Flexibilität. Beispielsweise können Texte transformiert oder Werte berechnet werden. Im Beispiel wird eine Zeichenfolge mit einem regulären Ausdruck auseinandergeschnitten, um anschließend Teile dessen zurückgegeben.

Im Import NuGet Paket ist die ObjectMapping-Klasse enthalten, welche das Mapping mit den Konvertern auf eine einfache Weise implementiert. Wenn dieses nicht verwendet werden soll, können diese natürlich auch “hart verdrahtet” werden. Ein Datenimport ist IMMER individuell.

ImportState

Die zweite Datei, die dem Importer übergeben enthält den ImportState. Dieser enthält das Mapping der Ids aus dem Fremdsystem und antony. Im Beispiel sehen wir das Mapping der “Projekte“. Das Objekt mit dem Identifier “bps://projekt/201857” ist in antony mit “antony://flexobject/26/31581” importiert worden. Etwaige Änderungen spiegeln sich in diesem Objekt nieder.

Antony verwendet für das Identifizieren URIs (https://diegroupware.atlassian.net/wiki/spaces/DEV/pages/113737729). Auf Seite des Fremdsystems ist dies ebenfalls sinnvoll.

{
  "ImportId": "94696bad-379f-43ed-bcf7-07ff5a135df8",
  "LastSyncUTC": "2022-01-10T13:21:57",
  "IdMappings": {
    "Projekte": {
      "bps://projekt/201857": "antony://flexobject/26/31581",
      "bps://projekt/201858": "antony://flexobject/26/31589"
    }
  }
}

ImportGroup und MappingName

Das ImportModul kann beliebig viele Importe gleichzeitig vornehmen, wobei jeder Import wiederrum einen eigenen ImportName aufweist. Es können sich mehrere Importe in der gleichen sogenannten ImportGroup befinden. Eine ImportGroup ist ein logischer Zusammenschluss von Import und ermöglicht den Zugriff auf die ImportStates der anderen Importe.

Der Anwendungsfall ist beispielsweise ein Flexobjekt, welches ein Feld mit einem Verweis auf einen Kontakt hat - wie zum Beispiel ein “Auftraggeber” Feld. In dem dazugehörigen, gemappten Feld muss sich die ID des antony-Kontakts (antony://contact/4711) befinden. Dies kann der Importer allerdings nur dann machen, wenn er die Kentniss vom Mapping der Kontakte hat. Die ImportGroup sorgt dafür, dass dieser Zugriff möglich ist. So kann der Importer die KontaktId des Fremdsystems generieren und über das Mapping in die AntonyId überführen.

Converter

Converter können für die Umwandung “im Kleinen” für Anpassungen genutzt werden. Sie werden im AntonyImportModule konfiguriert und im Importer.exe ausgeführt. Sie dienen dazu die Werte inhaltlich anzupassen. Im NuGet Paket sind die standardmäßigen Konverter bereits enthalten.

Zusammenfassung

Dieser Artikel dient dafür, dass Sie einen groben Einblick in die Funktionsweise des Imports erhalten. Die Konfiguration finden Sie in den Unterpunkten.

antony Handbuch 2.x

Kontinuierlicher Datenimport