Zum Hauptinhalt springen

Mapping und Transformationen

Für jede Operation muss ein Mapping definiert werden. Dabei gibt es zwei Möglichkeiten, ein Mapping anzugeben:

Das mapping Request Schema ist hier unter operations → mapping zu finden.

  • SingleMappingDto: Hierbei wird ein sourceField auf ein targetField abgebildet. Der Wert aus dem sourceField kann optional über die Eigenschaft transform transformiert werden, bevor er dem targetField zugewiesen wird. Das mapping kann in diesem Fall eine Liste von SingleMappingDto-Objekten oder ein einzelnes SingleMappingDto-Objekt sein.

  • GroupMappingDto: In diesem Fall werden Einträge anhand der in groupByFields angegebenen Felder gruppiert. Über die Eigenschaft keyInGroupResult eines groupByFields-Eintrags kann gesteuert werden, ob und wie das Feld in die Ausgabe übernommen wird:

    • Wenn true, wird das Feld mit seinem Originalnamen in den Ausgabedatensatz aufgenommen.
    • Wenn ein String angegeben wird, wird das Feld unter diesem Namen in die Ausgabe übernommen.

Im groupByFields kann zusätzlich über die Eigenschaft transform eine oder mehrere Transformationen definiert werden, die auf den Feldwert angewendet werden, bevor dieser für die Gruppierung verwendet wird.

Die gruppierten Einträge werden anschließend unter dem Feld itemsTargetField in der Ausgabe zusammengeführt. Die Mappings für die einzelnen gruppierten Elemente werden in itemsMapping definiert.

Wird ein GroupMappingDto verwendet, darf das mapping ausschließlich genau ein GroupMappingDto-Objekt enthalten.

TransformObject und Transformer​

Die Mappings nutzen Transformationen der Daten. Beispiele dafür finden Sie hier, welche Sie anschließend in den jeweiligen SingleMappingDto oder GroupMappingDto verwenden können.

Beispiele​

Beispiel 1​

{
    "transform": {
        "transformerType": "trim",
        "trim": true
    }
}

Beispiel 2​

{
    "transform": [
        {
            "transformerType": "substring",
            "start": 6,
            "end": -2
        },
        {
            "transformerType": "parseFloat",
            "parseFloat": true
        },
        {
            "transformerType": "formatDate",
            "targetFormat": "YYYY-MM-DD"
        }
    ]
}

Beispiel 3​

{
    "transform": {
        "transformerType": "replace",
        "isRegExp": true,
        "searchValue": "[A-Za-z]+",
        "replaceValue": ""
    }
}

Beschreibung​

transform TransformObject oder Array von TransformObject, optional, default: undefined​

  • Transformations Optionen die nach dem holen der Daten und vor dem senden der Daten ausgeführt werden. Wenn ein Array von Transformations Optionen übergeben wird, dann werden diesen nacheinander vom ersten bis zum letzten Element verarbeitet. Dabei ist die Ausgabe einer Transformations Option die Eingabe der nächsten Transformations Option.
Beschreibung TransformObject​
  • Beschreibt die auszuführende Transformation.
transformerType string​
  • Gibt die Aktion der Transformation an.
Beschreibung TrimTransformer​
  • Entfernt Leerzeichen am Anfang und Ende des Strings.
transformerType = "trim"​
  • Gibt die Aktion der Transformation an.
Beschreibung TakeTransformer​
  • Nimmt die ersten in take angegebenen Zeichen des Strings.
transformerType = "take"​
  • Gibt die Aktion der Transformation an.
take number​
  • Gibt an wie viele Zeichen vom Anfang genommen werden.
Beschreibung SubstringTransformer​
  • Extrahiert einen Substring aus dem String.
transformerType = "substring"​
  • Gibt die Aktion der Transformation an.
start number​
  • Startindex des Substrings; negative Werte zählen vom Ende des Strings.
end number, optional, default: Länge des inputs​
  • Endindex des Substrings (nicht inklusive); negative Werte zählen vom Ende des Strings.
Beschreibung ReplaceTransformer​
  • Ersetzt alle Vorkommen eines Strings durch einen anderen.
transformerType = "replace"​
  • Gibt die Aktion der Transformation an.
searchValue string​
  • Suchwert, der ersetzt werden soll.
  • Wird als reguläre Expression (RegExp) interpretiert, wenn isRegExp auf true gesetzt ist.
  • Aufgrund von Encoding-Problemen kann momentan kein \ in der RegExp verwendet werden.
replaceValue string​
  • Ersetzungswert.
isRegExp boolean, optional, default: false​
  • Wenn true, wird searchValue als reguläre Expression behandelt, andernfalls als normaler String.
Beschreibung RoundTransformer​
  • Rundet eine Zahl auf in round angegebenen Nachkommastellen.
transformerType = "round"​
  • Gibt die Aktion der Transformation an.
round number​
  • Gibt die Anzahl der Nachkommastellen an, auf die die Zahl gerundet wird.
Beschreibung FormatDateTransformer​
  • Formatiert ein Datum, das als String, Number oder Date übergeben wird.
transformerType = "formatDate"​
  • Gibt die Aktion der Transformation an.
format string, optional, default: "YYYY-MM-DD"​
  • Format des Datums des Inputs.
  • Ist das Feld leer, wird versucht, das Datum im Format "YYYY-MM-DD" einzulesen.
  • Im hintergrund wird day.js verwendet und daher können alle in day.js verwendeten Input Formate verwendet werden. (Siehe auch)
targetFormat string, optional, default: "YYYY-MM-DDTHH:mm:ssZ[Z]"​
  • Ziel-Format des Datums, ist das Feld leer, wird das Datum im ISO8601-Format zurückgegeben.
  • Im hintergrund wird day.js verwendet und daher können alle in day.js verwendeten Output Formate verwendet werden. (Siehe auch)
Beschreibung ParseFloatTransformer​
  • Konvertiert einen String in eine Fließkommazahl.
transformerType = "parseFloat"​
  • Gibt die Aktion der Transformation an.
Beschreibung ParseFloatToStringTransformer​
  • Konvertiert eine Zahl in einen String.
transformerType = "parseFloatToString"​
  • Gibt die Aktion der Transformation an.
Beschreibung ParseBooleanTransformer​
  • Konvertiert einen String oder eine Zahl in einen Boolean.
  • Bei einem String wird "true" zu true, alle anderen Strings zu false.
  • Bei einer Zahl wird 1 zu true, alle anderen Zahlen zu false.
  • Bei anderen Datentypen bleibt der Wert unverändert.
transformerType = "parseBoolean"​
  • Gibt die Aktion der Transformation an.

SingleMappingDto​

Das SingleMappingDto Request Schema ist hier unter operations → mapping → SingleMappingDto zu finden.

Beispiele​

Beispiel 1​

{
    "sourceField": "CostCenter._CostCenter.name",
    "targetField": "cost_center_id",
    "transform": {
        "transformerType": "trim",
        "trim": true
    }
}

Beispiel 2​

{
    "sourceField": "CostCenter._CostCenter.creationDate",
    "targetField": "cost_center_creation_date",
    "isUpdateKey": false,
    "transform": [
        {
            "transformerType": "substring",
            "start": 6,
            "end": -2
        },
        {
            "transformerType": "parseFloat",
            "parseFloat": true
        },
        {
            "transformerType": "formatDate",
            "targetFormat": "YYYY-MM-DD"
        }
    ]
}

Beispiel 3​

{
    "sourceField": "CostCenter._CostCenter.name",
    "targetField": "cost_center_id",
    "isUpdateKey": true,
    "transform": {
        "transformerType": "replace",
        "isRegExp": true,
        "searchValue": "[A-Za-z]+",
        "replaceValue": ""
    }
}

Beschreibung​

sourceField string​

  • Pfad zum Feld in den Quelldaten, der auch auf verschachtelte Objekte und Arrays zugreifen kann.
    Beispiel: "user.address.city" greift auf das city-Feld im address-Objekt des user-Objekts zu.

targetField string​

  • Pfad zum Feld in den Zieldaten, der auch auf verschachtelte Objekte und Arrays zugreifen kann.
    Beispiel: "order.items[0].quantity" greift auf das erste Element im items-Array und dessen quantity-Feld zu.

isUpdateKey boolean, optional, default: false​

  • Kennzeichnet, ob das jeweilige Mapping-Feld als Identifikationsschlüssel für Datenupdates dient. Wird isUpdateKey auf true gesetzt, so werden beim Aktualisieren der Datenbank alle Felder, die als UpdateKeys markiert sind, in die WHERE-Klausel der Update-Abfrage einbezogen. Die Bedingung stellt sicher, dass die Werte dieser Felder aus den SAP-Daten exakt mit den entsprechenden Werten in der Datenbank übereinstimmen, wodurch die Eindeutigkeit des zu aktualisierenden Datensatzes gewährleistet wird. Beispiel: Bei einem Mapping-Eintrag mit sourceField: "Kundennummer", targetField: "customer_id" und isUpdateKey: true wird sichergestellt, dass beim Update in der Datenbank nur der Datensatz geändert wird, dessen customer_id exakt dem Wert der Kundennummer aus den SAP-Daten entspricht.
  • Hinweis: Diese Option wird nur berücksichtigt, wenn ein Update von SAP in die Datenbank erfolgt. Konkret gilt: Wenn in der Konfiguration im entsprechenden Objekt des operations-Arrays, in dem dieses Mapping definiert ist, die direction auf den Wert SAP_TO_DB und in der Konfiguration in der databaseConnection die Option clear auf false gesetzt ist.

GroupMappingDto​

Das GroupMappingDto Request Schema ist hier unter operations → mapping → GroupMappingDto zu finden.

Beispiele​

Beispiel 1​

  • groupByFields: Die Daten werden anhand des Werts im Feld id (key) gruppiert und im Ausgabedatensatz unter dem Feldnamen ID (keyInGroupResult) übernommen.
  • itemsTargetField: Die gruppierten Einträge werden im Ausgabedatensatz als Array im Feld items abgelegt.
  • itemsMapping: Das Feld itemId aus den Eingabedaten (sourceField) wird in den einzelnen Items des Arrays im Ausgabedatensatz unter id (targetField) gespeichert.
Input​
[
    { "id": 0, "itemId": 0 },
    { "id": 0, "itemId": 1 },
    { "id": 0, "itemId": 2 },
    { "id": 1, "itemId": 0 },
    { "id": 1, "itemId": 1 },
    { "id": 1, "itemId": 2 },
    { "id": 2, "itemId": 0 },
    { "id": 2, "itemId": 1 },
    { "id": 2, "itemId": 2 }
]
Mapping​
{
    "groupByFields": { "key": "id", "keyInGroupResult": "ID" },
    "itemsTargetField": "items",
    "itemsMapping": { "sourceField": "itemId", "targetField": "id" }
}
Output​
[
    {
        "ID": 0,
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": 1,
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": 2,
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    }
]

Beispiel 2​

  • groupByFields: Die Daten werden anhand des Werts im Feld id gruppiert und im Ausgabedatensatz unter dem Feldnamen ID (keyInGroupResult) übernommen. Die zugehörigen Werte werden dabei in einen String konvertiert (transform) auf dessen Basis auch die Gruppierung stattfindet.
  • itemsTargetField: Die gruppierten Einträge werden im Ausgabedatensatz als Array im Feld items abgelegt.
  • itemsMapping: Das Feld itemId aus den Eingabedaten (sourceField) wird in den einzelnen Items des Arrays im Ausgabedatensatz unter id (targetField) gespeichert.
Input​
[
    { "id": 0, "itemId": 0 },
    { "id": 0, "itemId": 1 },
    { "id": 0, "itemId": 2 },
    { "id": 1, "itemId": 0 },
    { "id": 1, "itemId": 1 },
    { "id": 1, "itemId": 2 },
    { "id": 2, "itemId": 0 },
    { "id": 2, "itemId": 1 },
    { "id": 2, "itemId": 2 }
]
Mapping​
{
    "groupByFields": {
        "key": "id",
        "keyInGroupResult": "ID",
        "transform": { "transformerType": "parseFloatToString" }
    },
    "itemsTargetField": "items",
    "itemsMapping": { "sourceField": "itemId", "targetField": "id" }
}
Output​
[
    {
        "ID": "0",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": "1",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": "2",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    }
]

Beispiel 3​

  • groupByFields: Die Daten werden anhand des Werts im Feld id gruppiert und im Ausgabedatensatz unter dem Feldnamen ID (keyInGroupResult) übernommen. Dabei wird vor der Gruppierung eine Substring-Transformation angewendet, um nur das erste Zeichen der id zu berücksichtigen.
  • itemsTargetField: Die gruppierten Einträge werden im Ausgabedatensatz als Array im Feld items abgelegt.
  • itemsMapping: Das Feld itemId aus den Eingabedaten (sourceField) wird in den einzelnen Items des Arrays im Ausgabedatensatz unter id (targetField) gespeichert.
Input​
[
    { "id": "01", "itemId": 0 },
    { "id": "02", "itemId": 1 },
    { "id": "03", "itemId": 2 },
    { "id": "11", "itemId": 0 },
    { "id": "12", "itemId": 1 },
    { "id": "13", "itemId": 2 },
    { "id": "21", "itemId": 0 },
    { "id": "22", "itemId": 1 },
    { "id": "23", "itemId": 2 }
]
Mapping​
{
    "groupByFields": {
        "key": "id",
        "keyInGroupResult": "ID",
        "transform": { "transformerType": "substring", "start": 0, "end": 1 },
    },
    "itemsTargetField": "items",
    "itemsMapping": [{ "sourceField": "itemId", "targetField": "id" }]
}
Output​
[
    {
        "ID": "0",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": "1",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    },
    {
        "ID": "2",
        "items": [{ "id": 0 }, { "id": 1 }, { "id": 2 }]
    }
]

Beispiel 4​

  • groupByFields: Die Daten werden anhand des Werts im Feld id und subId gruppiert und im Ausgabedatensatz unter dem Feldnamen ID (keyInGroupResult) übernommen. Die zugehörigen Werte werden dabei in einen String konvertiert (transform) auf dessen Basis auch die Gruppierung stattfindet. Das Feld subId wird dabei nicht in den Ausgabedatensatz übernommen.
  • itemsTargetField: Die gruppierten Einträge werden im Ausgabedatensatz als Array im Feld items abgelegt.
  • itemsMapping: Das Feld itemId aus den Eingabedaten (sourceField) wird in den einzelnen Items des Arrays im Ausgabedatensatz unter id (targetField) gespeichert.
Input​
[
    { "id": 0, "subId": 1, "itemId": 0 },
    { "id": 0, "subId": 1, "itemId": 1 },
    { "id": 0, "subId": 2, "itemId": 0 },
    { "id": 0, "subId": 2, "itemId": 1 },
    { "id": 1, "subId": 1, "itemId": 0 },
    { "id": 1, "subId": 1, "itemId": 1 },
    { "id": 1, "subId": 2, "itemId": 0 },
    { "id": 1, "subId": 2, "itemId": 1 }
]
Mapping​
{
    "groupByFields": [{ "key": "id", "keyInGroupResult": "ID" }, "subId"],
    "itemsTargetField": "items",
    "itemsMapping": [{ "sourceField": "itemId", "targetField": "id" }]
}
Output​
[
    {
        "ID": 0,
        "items": [{ "id": 0 }, { "id": 1 }]
    },
    {
        "ID": 0,
        "items": [{ "id": 2 }, { "id": 3 }]
    },
    {
        "ID": 1,
        "items": [{ "id": 0 }, { "id": 1 }]
    },
    {
        "ID": 1,
        "items": [{ "id": 2 }, { "id": 3 }]
    }
]

Beschreibung​

GroupMappingDto​

groupByFields string | GroupByField | (string | GroupByField)[]​
  • Gibt an, nach welchen Feldern die Eingabedaten gruppiert werden.
  • Einfache Gruppierung erfolgt über einen Feldnamen (z. B. "id").
  • Mit einem GroupByField können über die transform-Eigenschaft Transformationen auf den Gruppierungswert angewendet werden.
  • Mehrfach-Gruppierung ist per Array aus Strings und/oder GroupByField möglich.
itemsTargetField string​
  • Gibt den Feldnamen im Ausgabedatensatz an, unter dem die gruppierten Items als Array abgelegt werden.
itemsMapping SingleMappingDto | SingleMappingDto[] | GroupMappingDto​
  • Beschreibt, wie die Felder der gruppierten Items in die Zieldaten übertragen werden.

GroupByField​

key string​
  • Pfad zum Feld in den Quelldaten, das als Gruppierungskriterium dient.
keyInGroupResult string | boolean, optional, default: false​

Bestimmt, ob und unter welchem Schlüssel ein Wert aus den Quelldaten in den Ausgabedatensatz übernommen wird.

  • string: Der Wert unter key wird aus den Quelldaten gelesen und im Ausgabedatensatz unter dem angegebenen string-Schlüssel gespeichert.
  • true: Der Wert unter key wird aus den Quelldaten gelesen und im Ausgabedatensatz unter dem gleichen Schlüssel (key) gespeichert.
  • false oder nicht definiert: Der Wert unter key wird nicht in den Ausgabedatensatz übernommen.
transform object oder Array von Objekten, optional, default: undefined​
  • Transformation(en), die auf den Wert angewendet werden, bevor er für die Gruppierung verwendet wird (siehe Beschreibung transform unter SingleMappingDto).
info

Die Verwendung von GroupMappingDto ist nur dann sinnvoll, wenn Daten aus der Datenbank zu SAP übertragen werden sollen und SAP eine verschachtelte Datenstruktur erwartet. Die Datenbank hingegen erwartet stets ein Array von Key‑Value‑Objekten in flacher Struktur.

Um verschachtelte SAP‑Daten in das flache Datenbankformat zu transformieren, kann einfach das Feld sourceField des Typs SingleMappingDto genutzt werden. Dort lässt sich ein Pfad angeben, um direkt auf beliebige verschachtelte Felder zuzugreifen.