Key Mapping Dialog (data transpiler) JSON-Mapping in getaiplan für Importschnittstellen

Key Mapping Dialog (Data Transpiler)

JSON‑Mapping in getaiplan für Importschnittstellen

In getaiplan lassen sich über den Bereich Integration Daten aus externen Systemen (ERP, HR, MES, Zeiterfassung …) automatisch übernehmen. Ein JSON‑basiertes Mapping ordnet dabei jede Quellspalte einem Systemfeld zu und legt fest, wie fehlende Werte, Transformationen oder verschachtelte Objekte gehandhabt werden.

Prinzip  –  Ob Du Mitarbeitende, Fertigungsaufträge, Abwesenheiten oder Zeitbuchungen importierst: Die Mapping‑Syntax ist immer gleich, nur die Ziel‑Felder ändern sich.

1  Grundstruktur & Pflichtfelder

Ein Mapping‑JSON besteht immer aus den drei Pflichtschlüsseln ga_type, ga_datatype und ga_structure.

{
  "ga_type": "userdata",        // Import‑Typ (z. B. userdata, absencedata …)
  "ga_datatype": "dict",        // Struktur des Quellobjekts (dict | list)
  "ga_structure": {              // Rekursives Mapping der Felder
    …
  }
}

1.1  Alle verfügbaren Mapper‑Felder

2  Basis‑Mapping – Minimalbeispiel

{
  "ga_type": "userdata",
  "ga_datatype": "list",
  "ga_structure": {
    "ExterneID": "EXTERNID",
    "Vorname":   "FIRSTNAME",
    "Nachname":  "LASTNAME"
  }
}

Jeder Listeneintrag im Import wird zu einem Mitarbeitenden mit EXTERNID, FIRSTNAME und LASTNAME.

3  Advanced Mapping Patterns

Nutze diese Bausteine einzeln oder kombiniere sie – die Mapper‑Engine arbeitet jedes Element in der angegebenen Reihenfolge ab.

3.1  Feste Werte zuweisen (Konstanten)

Wenn ein Zielfeld immer denselben Wert erhalten soll, kannst Du ein Dummy‑Quellfeld anlegen, das in der Datei gar nicht vorkommt. Über ga_default_missing setzt der Mapper dann automatisch den gewünschten Fixwert.

"dummyCostCenter": {
  "ga_target": ["COSTCENTER"],
  "ga_default_missing": "CC‑1234"
}

Logik

• Das Feld dummyCostCenter ist in der Quelle nicht vorhanden ⇒ gilt für jeden Datensatz als missing.

• ga_default_missing injiziert deshalb bei jedem Import den konstanten Wert CC‑1234 in das Zielfeld COSTCENTER.

• Möchtest Du den Wert nur als Fallback nutzen, gib stattdessen den echten Spaltennamen als Key an – der Default greift dann ausschließlich, wenn die Spalte fehlt.

3.2  Defaultwerte bei fehlenden oder leeren Feldern  Defaultwerte bei fehlenden oder leeren Feldern

"Telefon": {
  "ga_target": "PHONE",
  "ga_default_missing": "0000",
  "ga_default_empty":   "0000"
}

Logik

• ga_default_missing greift nur, wenn das Quellfeld gar nicht vorhanden ist.

• ga_default_empty greift, wenn das Feld zwar existiert, aber leer ("") ist.

• Sind beide Parameter gesetzt, prüft der Mapper zuerst auf missing, dann auf empty.
  

Komplexe Defaultwerte

"Telefon": {
  "ga_target": "PHONE",
  "ga_default_missing": "func(datetime:now)",
}

• fügt “jetzt” als Wert ein

• datetime steht für den Datentyp

• Aktuell zur Verfügung stehen:

  • datetime:now => aktuelle Uhrzeit gemäß Zeitzone des Servers (Frankfurt)

  • datetime:utc=> aktuelle Uhrzeit in UTC (+0)

  • date:today => heutiges Datum

3.3  Ein Quellfeld → mehrere Zielfelder

"VollerName": ["FIRSTNAME", "LASTNAME"]

Logik

• Der Wert von VollerName wird dupliziert und in alle angegebenen Zielfelder geschrieben.

• Praktisch für Systeme, die Vor‑ und Nachname in einer Spalte liefern, Du sie aber getrennt pflegen möchtest (später kann z. B. eine ga_transform‑Funktion auf den Zielfeldern greifen).

3.4  Mehrere Quellfelder → ein Listen‑/Set‑Zielfeld

"Sprache1": "LANGUAGES",
"Sprache2": "LANGUAGES",
"Sprache3": "LANGUAGES"

Logik

• Alle Quellwerte werden gesammelt und als Liste / Menge im Zielfeld gespeichert.

• Funktioniert nur, wenn das Zielfeld in getaiplan als Liste oder Set konfiguriert ist (erkennbar an eckigen Klammern in der Feldreferenz).

• Ist das Zielfeld ein einfacher String, überschreibt der letzte Wert die vorherigen → siehe 3.5.

3.5  Last‑Value‑Wins (Fallback‑Kaskade)

"email1": "EMAIL",   // höchste Priorität 
"email2": "EMAIL"    // überschreibt email1, falls vorhanden

Logik

• Mappt mehrere Quellfelder auf dasselbe einzel­wertige Zielfeld.

• Der Mapper arbeitet von oben nach unten – der unterste gültige Wert gewinnt.

• So kannst Du eine einfache Prioritäts‑/Fallback‑Reihenfolge definieren, ohne separate IF‑Logik.

3.6  Transformationen

• ga_transform verändert den Wert nachdem er aus der Quelle gelesen wurde, bevor er ins Zielfeld geschrieben wird.

• Typische Anwendungsfälle:

  • Mehrere Felder zusammenführen (concatstring_with)

  • Felder verändern (z.b. boolische Auswertungen)

• Transformationen lassen sich mit Defaults und ga_ignore kombinieren.

3.6.1 Felder kombinieren

Diese Funktion kann andere Funktionen oder Felder als Eingabe nutzen. Das ist im letzten Beispiel der Funktion beshrieben.

"Straße":   {
    "ga_target": "ADDRESS",
    "ga_transform": "concatstring_with(fields=[Hausnr], separator=' ' )"
  }

Logik

• fields: Felder die mit dem aktuellen Feld kombiniert werden sollen, mehrere Felder können getrennt durch ein “;” angegeben werden

• seperator: Trennzeichen zwischen den Feldern

Beispiel mit Schachtelung

"Straße":   {
    "ga_target": "ADDRESS",
    "ga_transform": "concatstring_with(fields=[Hausnr;ga_transform:substr(1,-1,data='PLZ')], separator=' ' )"
  }

Hier werden die Felder Hausnr und das Feld PLZ kombiniert. Wobei von PLZ das erste und das letzte Zeichen entfernt werden.

3.6.2 Felder umwandeln

Diese Funktion kann andere Funktionen oder Felder als Eingabe nutzen. Das ist im letzten Beispiel der Funktion beshrieben.

"Straße":   {
    "ga_target": "ADDRESS",
    "ga_transform": "cast('bool','==','014')"
  }

Logik

• Die Cast Funktion besteht aus 3 Elementen

  • ‘bool’ => Zieldatentyp (Aktuell stehen zur Verfügung: bool)

  • ‘==’ Operator für die Umwandlung (Aktuell stehen zur Verfügung: !=, ==, <, >, <=, >=)

  • ‘014’ Wert gegen den geprüft wird

• Im Beispiel wird zu True evaluiert, falls der übergebene Wert gleich 014 ist, sonst wird zu False evaluiert

Beispiel mit Schachtelung

"Straße":   {
    "ga_target": "ADDRESS",
    "ga_transform": "cast('bool','==','014', data='ga_transform:substr(1,-1,data='PLZ')')"
  }

• Es wird geprüft ob der Wert gleich “014” ist. Hierbei wird allerdings nicht das Feld “Straße” geprüft, sondern es wird erst eine weitere Transformation ausgeführt. Für die Eingabe der zweiten Transformation wird das Feld “PLZ” genutzt.

3.6.3 Texte kürzen und zuschneiden

Diese Funktion kann andere Funktionen oder Felder als Eingabe nutzen. Das ist im letzten Beispiel der Funktion beshrieben.

"Nutzer":   {
    "ga_target": "PRENAME",
    "ga_transform": "substr(1)"
  }

Überspringt das erste Zeichen. Aus “ABC” wird also “BC”

"Nutzer":   {
    "ga_target": "PRENAME",
    "ga_transform": "substr(0,-1)"
  }

Überspringt das letzte Zeichen. Aus “ABC” wird also “AB”

Beispiel mit Schachtelung

"Nutzer":   {
    "ga_target": "PRENAME",
    "ga_transform": "substr(1,-1,data='SURNAME')"
  }

Überspringt das erste und letzte Zeichen und nutzt den Wert aus einem anderen Feld, oder einen anderen Funktion. Wenn das Feld “Surname” den Wert “Ron” hätte, würde für PRENAME also nur “o” gesetzt

3.6.4 Funktionen schachteln

Einige Funktionen können geschachtelt werden. Das ist direkt an den Funktionen angegeben.

Für einige Funktionen steht hier ein optionales Feld “data” zur Verfügung. Bei anderen, wie beim Zusammenfügen, kann eine andere Funktion direkt als Input angegeben werden.

Eine weitere Transformation wird immer angegeben als

ga_transform:<Funktion>

Wobei <Funktion> entsprechend zu ersetzen ist.

Die Schachtelung kann beliebig tief erfolgen und wird von innen nach außen ausgewertet. Dies entspricht dem Konzept von higher-order functions in der Mathematik und Programierung.

3.7  Bedingtes Ausfiltern (ga_ignore)

"Status": {
  "ga_ignore": "!= AKTIV"
}

Logik

• Der Ausdruck in ga_ignore wird pro Datensatz ausgewertet.

• Ist er wahr, wird der gesamte Datensatz übersprungen – inklusive aller Unterelemente.

• Unterstützte Operatoren: ==, !=, <, <=, >, >=

• ga_ignore wird vor Defaults, Transformationen oder Vererbungen angewendet, spart also Verarbeitungszeit.

4  Spezialfunktionen aus dem Mapper‑Code

4.1  Verschachtelte Listen (ga_target, ga_copyparent)

{
  "ga_datatype": "list",
  "ga_target": "SHIFTNEEDS",
  "ga_structure": { … }
}

Erzeugt im Elternobjekt ein Feld SHIFTNEEDS mit einer Liste der Untereinträge.

Mit ga_copyparent kann bestimmt werden, dass bei geschachtelten Listen alle Elemente der Kindliste die Werte des Elternelements bekommen, das Elternelement selbst, alleine für sich, kein valides Datum ist. Damit können auch geschachtelte Daten, wobei in innere Liste die Daten spezifiziert geparst werden. Als Beispiel wäre eine Liste von Fertigungsaufträgen zu nennen, wobei jeder Auftrag eine Liste mit Vorgängen hat. Und zu jedem der Vorgänge soll die Anzahl der produzierten Teile importiert werden. Allerdings sind die Vorgänge nicht voll beschreibend, sondern benötigen Daten aus dem Fertigungsauftrags selbst.

4.3  Vererbbare Schlüssel & Upserts

Felder wie EXTERNID, CLIENT oder ORGUNIT können als Primärschlüssel definiert sein. Stimmen alle vererbbaren Felder, aktualisiert der Import den bestehenden Datensatz – andernfalls wird ein neuer angelegt.

4.4  Inline‑Transformationen (ga_transform)

Achtung – Transformationsfunktionen werden kontinuierlich erweitert. Prüfe die Release‑Notes für neue Optionen.

4.5  Fehlerdiagnose (Dialog „Zeige Fehler“)

5  Use‑Case‑Bibliothek

Tipp – Nutze die Beispiele als Blaupause und passe nur die Feldnamen an.

UC1  Fester Ersatzwert bei fehlender E‑Mail

"emailFeld": {
  "ga_target": ["EMAIL"],
  "ga_default_missing": "default@example.com"
}

UC2  Einheitliche Org‑Einheit trotz inkonsistenter Quelle

"dummyfield": {
  "ga_target": ["FIRMSTRUCTURE"],
  "ga_default_missing": "Standard‑OE"
}

UC3  Sprachenliste (Beliebig viele Felder → Set)

"Sprache1": "LANGUAGES",
"Sprache2": "LANGUAGES",
"Sprache3": "LANGUAGES"

UC4  Hierarchischer Auftragsimport mit Schichtbedarfen

{
  "ga_type": "orderdata",
  "ga_datatype": "dict",
  "ga_structure": {
    "Auftragskopf": {
      "ga_datatype": "list",
      "ga_type": "orderdata",
      "ga_structure": {
        "OrderID": "EXTERNID",
        "Schichtliste": {
          "ga_datatype": "list",
          "ga_target": "SHIFTNEEDS",
          "ga_type": "shiftneeddata",
          "ga_structure": {
            "Datum": "SHIFTDATE",
            "Menge": "NEED"
          }
        }
      }
    }
  }
}

6  Best Practices

1. Iteriere in kleinen Schritten – erst Minimalmapping, dann Defaults, dann Filter.

2. Fallbacks konsequent setzen (ga_default_missing / ga_default_empty).

3. Tabellen klar strukturieren – Kopfzeilen pflegen oder Spaltenliste definieren.

4. ga_ignore** zuerst**: Datensätze, die rausfliegen, verschwenden keine Transform‑Zeit.

7  Benutzeroberfläche des Import‑Dialogs

Das folgende Bild zeigt den Dialog „Import Mitarbeiter“. Die Oberfläche ist für alle Import‑Typen (Mitarbeiter, Aufträge, Abwesenheiten …) nahezu identisch aufgebaut.

Quick Workflow

1. Connection wählen → 2) Mapping im JSON‑Editor anpassen → 3) Jetzt ausführen testen → → 4) Editor verlassen & Fehler prüfen → 5)Speichern (für den Live‑Betrieb).

Damit ist klar ersichtlich, wo Du welche Einstellungen vornimmst und wie die Live‑Prüfung hilft, Syntax‑ oder Zuordnungsfehler schon vor dem eigentlichen Import zu entdecken.