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
| a | b |
|---|---|
| 1 | 2 |
Mapping
a = a + 1
neueSpalte = Test
Ergebnis mappingMode = Default
| a | neueSpalte |
|---|---|
| 2 | Test |
Ergebnis mappingMode = Ungemappte Spalten werden durchgereicht (gemappte Spalten ersetzen Quellspalten, neue Spalten erscheinen am Ende).
| a | b | neueSpalte |
|---|---|---|
| 2 | 2 | Test |
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).
| a | neueSpalte | b |
|---|---|---|
| 2 | Test | 2 |
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 Filter.
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önnen.
Wie kann ich den Dateinamen der eingelesenen Datei in einer Spalte ausgeben?
Beispiel:
Sie lesen eine Excel-Datei mit dem Step ExcelReader 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 |
|
| 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 |
|
| 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 |
|
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 |