Mapper / SpreadsheetMapper Step

Der Mapper ist der wichtigste Step in Synesty Studio. Mit diesem Step kann man ein Spreadsheet bearbeiten und in ein anderes Spreadsheet umwandeln.

Der Step bietet einen umfangreichen Mapping-Editor, mit dem die Spalten des Spreadsheets bearbeitet werden können. 
Eine Anleitung zu den einzelnen Funktionen dieses Steps finden Sie hier.

Erweiterte Einstellungen

MappingMode

Mit dem mappingMode kann man einstellen, wie das eingestellte Mapping angewendet wird. Es gibt drei Optionen:

1. Standard - Ausgabe nur gemappter Spalten

Hier erscheinen nur gemappte Spalten im Output-Spreadsheet.

2.  Ungemappte Spalten werden durchgereicht (gemappte Spalten ersetzen Quellspalten, neue Spalten erscheinen am Ende)

In diesem Modus beinhaltet das Output-Spreadsheet alle im Mapping definierten Spalten und alle Spalten des Input-Spreadsheets. Pass-through bedeutet, dass alle Spalten des Input-Spreadsheets durchgeschleift werden.
Spalten im Mapping überschreiben Spalten mit gleichem Namen im Input-Spreadsheet.

Alle zusätzlichen Spalten im Mapping (die nicht im Input-Spreadsheet vorkommen), werden am Ende angefügt.

3. Ungemappte Spalten werden durchgereicht, aber gemappte Spalten erscheinen zuerst (gemappte Spalten ersetzen Quellspalten).

Auch in diesem Modus beinhaltet das Output-Spreadsheet alle im Mapping definierten Spalten und alle Spalten des Input-Spreadsheets (Pass-through) und auch alle im Mapping vorhandenen Spalten überschreiben Spalten mit gleichem Namen des Input-Spreadsheet.

Alle zusätzlichen Spalten im Mapping (die nicht im Input-Spreadsheet vorkommen), werden allerdings am Anfang hinzugefügt.

Beispiel für mappingMode

Input-Spreadsheet

ab
12

Mapping

a = a + 1

neueSpalte = Test

Ergebnis mappingMode = Default

aneueSpalte
2Test

Ergebnis mappingMode = Ungemappte Spalten werden durchgereicht (gemappte Spalten ersetzen Quellspalten, neue Spalten erscheinen am Ende).

abneueSpalte
22Test

Hier wird Spalte a überschrieben (Funktion wird angewendet), Spalte b wird durchgeschleift (pass-through) und die neue Spalte wird hinten angefügt. 

Ergebnis mappingMode = Ungemappte Spalten werden durchgereicht, aber gemappte Spalten erscheinen zuerst (gemappte Spalten ersetzen Quellspalten).

aneueSpalteb
2Test2

In diesem Modus werden die gemappten Spalten zuerst ausgeben, Spalte a und neueSpalte sind im Mapping enthalten und werden deshalb als zuerst ausgeben (Funktion wird angewendet), Spalte b wird durchgeschleift (pass-through) und hinten angefügt.


Wann brauche ich den Pass-Through Modus?

Der Modus Pass-through unmapped source columns ist sehr praktisch, wenn man z.B. ein großes Input-Spreadsheet mit 40 Spalten hat, aber man nur zwei Spalten per Funktion bearbeiten will, aber trotzdem alle Spalten des Input-Spreadsheets auch wieder (unangetastet) im Output-Spreadsheet sehen möchten. In diesem Fall reicht es, wenn man dem Mapping nur die zwei zu bearbeitenden Spalten hinzufügt, statt alle 40 Spalten im Mapping zu definieren, wovon 38 einfach nur durchschleifen. Ein weiterer Effekt davon ist, dass auf diese Weise auch neue Spalten im Input-Spreadsheet automatisch mit durchgeschleift werden. Das ist praktisch z.B. ein Lieferant neue Felder in einer CSV-Datei schickt, die man automatisch unangetastet importieren will, aber auf wenige bekannte Felder noch Funktionen anwenden will. D.h. man kümmert sich nur um die wenigen Spalten, die man bearbeiten möchte, alles andere bleibt unangetastet.

Warnungen Deaktivieren

Die Option disableWarnings kann genutzt werden, um Warnungen zu deaktivieren. Siehe Warnungen und Fehlermeldungen.

CacheMode Aktivieren

Die Option cacheMode kann genutzt werden, um das Ergebnis des Mappers zwischen zu speichern.

Wann sollte das aktiviert werden?
Sobald im zwei oder mehr Steps das Filter-Ergebnis verwenden. Dann kann bei diesem Mapper der CacheMode aktiviert werden, um die Laufzeit zu verringern.

Hinweis:

Bei aktiviertem CacheMode gibt es eine Einschränkung. Der Zugriff von Varianten-Zeilen auf Parent-Zeilen funktioniert, aber der Zugriff von Child-Zeilen auf Master-Zeilen funktioniert nicht. 
D.h. man kann ${parent['columnname']} benutzen, jedoch nicht ${master['columnname']}. (Siehe auch Auf Relationen zugreifen). Aus diesem Grund ist der CacheMode standardmäßig deaktiviert.

Cookbook zum Thema CacheMode

Lesen Sie mehr zum Thema im Cookbook Reduzierung von Laufzeiten durch Einsatz vom CacheMode im Mapper und Filteropen in new window.

Anwendungsbeispiel

Den Mapper findet man meistens nach Steps, welche ein SPREADSHEET als Output haben. Dieses Spreadsheet wird dann damit aufbereitet und in einem späteren Step verwendet, so wie im Screenshot.

Ziel-Schema für Validierung und Filterung

Man kann im Mapper auch ein Schema hinterlegen (siehe Datastores#Schema). Damit hat man die Möglichkeit die Zielwerte die durch das Mapping entstehen auch zu validieren, d.h. zu prüfen, ob die Werte gemäß der Schema-Definition korrekt sind. 
Das ist praktisch, da Fehler visuell hervorgehoben werden und man invalide Daten auch direkt herausfiltern kann.

Um ein Schema auf ein Spreadsheet anzuwenden, klicken Sie auf Spalten / Schema laden und wählen das Schema.

Achtung

Durch das Laden eines Schemas wird die aktuelle Spaltenkonfiguration überschrieben. Wir empfehlen ein Schema gleich zu Beginn der Bearbeitung des Spreadsheets zu laden.

Das geladene Schema wird am Mapper Step gespeichert unter Erweiterte Optionen / targetSchemaName und kann dort auch zurückgesetzt werden.

Warnungen und Fehlermeldungen

Warnung bei nicht (mehr) existierenden Spalten

Manchmal kommt es vor,dass sich Spaltenbezeichnungen von CSV- oder XLS-Dateien ändern. Nicht immer hat man darauf Einfluss. Damit man besser mitbekommt, wenn z.B. ein Lieferant Spaltenbezeichnungen der CSV-Datei ändert, wird jetzt eine Warnung im Flow-Eventlog ausgegeben. Diese Warnungen kommen vom Mapper Step, wenn eine Quellspalte benutzt wird, die es in der Quelle nicht mehr gibt.

Beispiel:

Beispiel

Row: 1
{article_id=Error: SourceColumn does not exist: ean}

Die Beispiel-Fehlermeldung sagt, dass in der Zeile 1 und Spalte article_id eine Quellspalte ean erwartet wird, die aber im Quell-Spreadsheet nicht mehr existiert. Das könnte z.B. passieren, wenn diese Spalte in der Quelle z.B. von "ean" in "ean13" umbenannt, oder gar entfernt wurde.

Sie sollten darauf hin den entsprechenden Mapper kontrollieren und in der Spalte article_id die Quellspalte anpassen und durch die neue korrekte Quellspalte ersetzen.

Hinweis

Falls Sie sich wundern, dass ihre Flows plötzlich mit einer Warnung versehen werden, dann könnte genau das die Ursache sein. Wenn Sie im Eventlog "SourceColumn name does not exist" finden, dann prüfen Sie alle Mapper, ob sie Quellspalten nutzen, die es im Quell-Spreadsheet nicht mehr gibt, oder die anders geschrieben werden.

Eine andere Ursache kann sein, dass sie ein Spreadsheet eines Steps verwenden, der je nach konfiguriertem "Mode" unterschiedliche Spalten in im Ausgabe-Spreadsheet hat. D.h. wenn sie den Mode in der Quelle anpassen und die Ausgabe dadurch plötzlich weniger Spalten hat, dann werden Sie wahrscheinlich diese Warnung im folgenden Mapper sehen, falls dieser eine der entfernten Quell-Spalten erwartet.

Der Flow wird auch trotz Warnung bis zum Ende ausgeführt. Aber diese Warnung kann darauf hindeuten, dass ein Problem vorliegt und einige Spalten nicht mehr so gefüllt sind, wie das vor den Warnungen der Fall war.

Das Error-Handling ist in dieser Richtung strenger geworden. Das hat ggf. Anpassungen zur Folge, damit sie diese Meldungen wieder weg bekommen. Dieser Mehraufwand rechtfertigt sich aber dadurch, dass sie dann auch bemerken, wenn wirklich ein Fehler vorliegt wenn Quellspalten plötzlich verschwinden.

Warnung bei ungemappten Werten

Flows werden im Status "WARNUNG" beendet, wenn Sie in einem Mapper ein unvollständiges Mappingset verwenden. 
Bei Bedarf können Sie diese Warnung auch deaktivieren, so dass der Flow nicht im Status "WARNUNG" endet.

Achtung

Wir raten Ihnen dies nur zu deaktivieren, wenn Sie sich sicher sind, dass die Warnung in Ordnung ist und es sich nicht um einen Fehler handelt. In der Regel deutet die Warnung darauf, dass Sie etwas vergessen haben, oder mit der Zeit neue Werte hinzu gekommen sind, die Sie im Mappingset nachtragen sollten.

Lesen Sie mehr über diese Warnung und was Sie tun könnenopen in new window.

Wie kann ich den Dateinamen der eingelesenen Datei in einer Spalte ausgeben?

Beispiel:

Sie lesen eine Excel-Datei mit dem Step ExcelReaderopen in new window ein, damit Sie ein SPREADSHEET bekommen.
Sie möchten den Dateinamen der Excel-Datei in einer Spalte des Spreadsheets ausgeben. Grund könnte sein, dass dieser Dateiname dynamisch ist, und sich z.B. täglich ändert.

Im Mapper Step der den ExcelReader Output konsumiert, sollte eine Variable Dateiname  auswählbar sein. Darin ist der Dateiname der Excel-Datei enthalten.

${_inputFilename!}

Hinweis

Dieser Mechanismus um auf den Dateinamen zuzugreifen funktioniert auch in folgenden Steps des API-Connector-Tools Add-Ons:

  • CSVReader
  • JSONReader
  • XMLReader
  • JSONReaderVisual
  • XMLReaderVisual

Inputs

Das sind die Optionen, mit denen man den Step konfigurieren kann.

Name Datentyp Beschreibung Pflichtfeld Werte
source SPREADSHEET Das zu mappende Quell-Spreadsheet. Ja
mappingdefinition STRING Die Mapping-Definition enthält die Konfiguration aller Ergebnis-Spalten. Nein
targetSchemaName STRING Optional: Name eines Schemas mit initialen Ziel-Spalten. Wenn gefüllt, dann wird das Mapping beim ersten Laden der Konfiguration mit den Spalten dieses Schemas gefüllt. Es kann nur ausgewählt werden, wenn noch nicht auf 'Konfigurieren' geklickt wurde. Später kann man 'Schema laden' in der Konfigurationsansicht nutzen, um ein anderes Schema zu laden. Nein
disableWarnings STRINGLIST Optional um verschiedene Warnungen zu deaktivieren. Nein
  • Unterdrücke Warnung für 'ungemappte Werte' in Mappingsets.
  • Unterdrücke Verarbeitungsfehler (z.B. Syntax Fehler, fehlende Quellspalten usw.)
mappingMode STRING Der Mapping-Modus, der bestimmt, wie das Mapping auf das Quell-Spreadsheet angewendet wird. Default - Nur die Spalten in der Mapping-Definition sind auch in der Ausgabe (WYSIWYG). 'Pass-through unmapped source columns' bedeutet, dass Spalten des Quell-Spreadsheets mit durchgereicht werden. D.h. dass das Ergebnis-Spreadsheet alle Spalten des Quell-Spreadsheet + Spalten aus der Mapping-Definition beinhaltet. Nein
  • Standard - Ausgabe nur gemappter Spalten
  • Ungemappte Spalten werden durchgereicht (gemappte Spalten ersetzen Quellspalten, neue Spalten erscheinen am Ende).
  • Ungemappte Spalten werden durchgereicht, aber gemappte Spalten erscheinen zuerst (gemappte Spalten ersetzen Quellspalten, neue Spalten erscheinen zuerst).
cacheMode STRING Ja, um Caching zu aktivieren. Das kann langsame Verarbeitung bei Verwendung des SpreadsheetMapper beschleunigen, wenn das Ergebnis-Spreadsheet von min. zwei weiteren Steps verarbeitet wird. (Hinweis: Der Zugriff von Varianten-Zeilen auf Parent-Zeilen funktioniert, aber der Zugriff von Child-Zeilen auf Master-Zeilen funktioniert nicht. D.h. man kann ${parent['columnname']} benutzen, jedoch nicht ${master['columnname']}.) Nein
  • Ja
  • Nein

Outputs

Das sind die Ergebnisse des Steps, die von nachfolgenden Steps, nach der Ausführung verwendet werden können.

Name Datentyp Beschreibung Pflichtfeld Werte
spreadsheet SPREADSHEET Das Ergebnis-Spreadsheet mit dem Ergebnis der Umwandlung. Hinweis: Dieses Spreadsheet ist 'lazy'. D.h. dieses Spreadsheet wird erst gefüllt, wenn ein späterer Step des eigentliche Ergebnis-Spreadsheet dieses Steps verarbeitet. (z.B. wenn Sie einen eine CSV-Datei mit dem SpreadsheetCSVWriter schreiben). Ja
unmappedValues SPREADSHEET Ein SPREADSHEET mit Informationen zu ungemappten Werten von Spalten, welche auf Mappingsets zugreifen. Sie können diese Liste benutzen, um daraufhin die Mappingsets manuell zu verfolgständigen. Dieses Spreadsheet ist auf max. 1000 Zeilen pro Spalte mit ungemappten Werten begrenzt. Der ungemappte Wert wird aus Performancegründen nach 100 Zeichen abgeschnitten. Ja
errors SPREADSHEET Ein Spreadsheet, welches nur beim Mapping aufgetretene Fehler beinhaltet (hilfreich zum Debugging). Sie können es benutzen, um z.B. eine CSV-Datei von Mapping-Fehlern zu erstellen. Hinweis: Dieses Spreadsheet ist 'lazy'. D.h. dieses Spreadsheet wird erst gefüllt, wenn ein späterer Step des eigentliche Ergebnis-Spreadsheet dieses Steps verarbeitet. (z.B. wenn Sie einen eine CSV-Datei mit dem SpreadsheetCSVWriter schreiben). Ja