Spreadsheets

Mehr zum Thema Scripting

Ergänzend zu dieser Seite empfehlen wir auch folgende Seite zum Thema Scripting sowie Spreadsheet-Funktionen.

Was ist ein Spreadsheet?

Ein Spreadsheet ist gedanklich wie eine Excel-Tabelle mit Spalten und Zeilen und stellt das zentrales Element und Bindeglied zwischen Steps in Synesty Studio dar. So können z.B. Daten eines Spreadsheets in einen Datastore eingefügt oder in einer CSV Datei gespeichert werden.
Der wichtigste Step in diesem Zusammenhang ist der Mapper SpreadsheetMapper (kurz Mapper), womit sich Spreadsheets an die eigenen Bedürfnisse anpassen lassen. Man kann damit z.B. Spalten umbenennen, entfernen und Funktionen anwenden. Selbst WENN-DANN Logik kann auf Spalten angewendet werden, um diese zu manipulieren. 

Die Abbildung zeigt, wie man mit dem genannten Mapper SpreadsheetMapper die Spalten bearbeiten kann. 

Erklärung zur Abbildung:

• Inhaltliche Komponenten (rot)
• Visuelle Komponenten (gelb)
• Vorschau der Daten (grün)

Titel

Der Wert Titel legt die Spaltenbezeichnung fest.

Quelle

Hier können Sie eine Spalte mit den Daten einer beliebigen Spalte aus der Quelldatei befüllen. So ist es z.B. denkbar, das die Spalte mit dem Titel “ArtikelID” mit den Daten der in der Quelldatei befindlichen Spalte “art_id” befüllt werden soll.

Wert

Das Feld Wert ist eine andere sehr flexible Möglichkeit die Daten der Spalte zu bestimmen. Dies kann auf zwei Arten geschehen:

• fester Wert
• dynamischer Wert über Script-Sprache

Achtung:

Wird das Feld Wert befüllt, wird die Auswahl von Feld “Quelle” (2.) überschrieben, d.h. nicht beachtet. Auf den Wert der Quelle kann man aber über folgende Variablen zugreifen:

• ${_currentValue!}
• ${_sourceValue!}

Eine große Stärke dieses Feldes ist, die Möglichkeit Logik mit Hilfe der Freemarker Scriptsprache einzubinden. Wir empfehlen Ihnen im Anschluss an diese Informationen sich diese Freemarker Beispiele anzusehen. Sie werden schnell sehen, welche vielfältigen Möglichkeiten sich mit Freemarker Befehlen in Spreadsheets ergeben. 

Damit können Sie z.B. eine Spalte aus verschiedenen anderen Spalten zusammenbauen, um z.B. einen Produkttitel dynamisch aus den Spalten Marke, Produktname, Farbe und Größe zu generieren. 

Verfügbare Daten für das Wert-Feld: (3a)

Nach Klick auf den  Button, stehen Ihnen alle verfügbaren Daten zum befüllen der Wert Spalte zur Verfügung.
Diese werden bei Auswahl, automatisch in die benötigte Freemarker Syntax umgeformt.

---

Daten aus der Quelle einfügen

Sie können mit dieser Option, ähnlich wie mit dem Quelle Feld auf jede Spalte der Quelldatei zugreifen. Anders als im Quelle Feld können Sie jedoch mehrere Werte, anstatt einer einzigen, hinzufügen.

Klicken Sie hier, um ein Beispiel anzuzeigen

Ausgangslage:

Sie haben in Ihrer Quelldatei eine Preisspalte “price” mit einem nummerischen Wert und eine Währungsspalte “pricecurrency”.

Ziel:

Das Zielsystem erwartet eine einzige Spalte “preis”, welche sowohl die Währung als auch den Preis beinhaltet. ( z.B. EUR_99.95 )

Vorgehen:

Nachdem Sie die Quelldatei in Synesty Studio geladen und diese als Input in den Step “Mapper SpreadsheetMapper” geladen haben, legen Sie eine neue Spalte mit dem Titel “preis” an, danach klicken auf den ”+” Button neben den Feld “Wert”.

In dem erscheinenden Fenster, wählen Sie die Quellspalte “pricecurrency”, anschließend wird das Feld “Wert” befüllt. Danach wird über die selbe Vorgehensweise die Spalte “price” hinzugefügt. Das Feld “Wert” hat nun den Inhalt ${pricecurrency}${price}. Die Daten (4.) der Spalte haben nun diese Form “EUR99.95”

Um das vorgegebene Trennzeichen ” ” einzufügen, wird dieses Zeichen lediglich zwischen die beiden Werte eingetragen. Somit ergibt sich als Resultat im “Wert” Feld: ${pricecurrency} ${price}

Hinweis

Über den Button ausgewählte (dynamische) Werte, werden automatisch in die Freemarker Syntax übersetzt. Dabei werden die Werte wie “Spaltenname” in einem Container ${} eingeschlossen. Alle festen Werte, müssen außerhalb dieses Containers eingefügt werden.

Hilfsvariablen

Hilfsvariablen, die immer verfügbar sind

Neben den Quellspalten können Sie hier auch noch zusätzliche Hilfsvariablen einfügen wie z.B.:

• ${_rowNumber!} - Zeilennummer (beginnend bei 1)
• ${_emptyValue!} - Leerwert (ein leerer String)
• ${_currentValue} - beinhaltet immer den aktuellen Wert. D.h. im Wertfeld ist das der Wert der Quellspalte. Weiter unten in den Spaltenfunktionen entspricht istes dann immer der Wert vor Anwendung der jeweiligen Funktion
• ${_currentTitle!} - Beinhaltet den aktuellen Spaltentitel
• ${_sourceValue} - ist immer der Wert der ausgewählten Quellspalte. Im Wertfeld ist es gleich ${_currentValue}
• ${_sourceTitle} - Ist der Name der aktuell gewählten Quellspalte

Hilfsvariablen im Datastore-Kontext

Spreadsheets, die aus Datastores kommen, haben ein paar Spezialfähigkeiten.

• ${row.changedContentCols} - Enthält eine Map (Key-Value Paare) mit Spalten, deren Inhalt sich beim letzten Schreibvorgang geändert hat.
  • ${row.changedContentCols?keys?join(",")} - Listet diese Spaltennamen komma-separiert auf
  • ${row.changedContentCols["col1"]!} - Gibt den vorherigen Wert einer inhaltlich geänderten Spalte aus (in diesem Beispiel der Spalte col1)

Hilfsvariablen bei Datei-Spreadsheets

Spreadsheets die auf Dateien (FILE) basieren (z.B. CSVReader) haben ebenfalls zusätzliche Fähigkeiten

• ${_inputFilename} - Enthält den Dateiname der zugrundliegenden Datei.

---

Automatisches Mapping der Quellspalten

Das initiale Konfigurieren des Mappers nimmt je nach System sehr viel Zeit und Konzentration in Anspruch.
Wir wissen, dass dieser Prozess mitunter sehr kräftezehrend sein und den Spaß an der Integrationsentwicklung rauben kann.
Darum möchten wir Ihnen diese Arbeit vereinfachen - mit der Funktion Vorschläge für Quellspalten holen.

Mappen Sie Ihre Zielspalten mit wenigen Klicks über den Menüpunkt Spalten > Vorschläge für Quellspalten holen

Das System wählt nun abhängig vom Namen der Zielspalten die ersten drei wahrscheinlichsten Quellspalten aus, die über ein Dropdown angewählt werden können.
Die angewählten Quellspalten können nun mit einem Klick direkt übertragen werden.

Je nach Spaltentitel kann die Vorhersage hier natürlich mehr oder weniger sinnvoll sein.
Darum gibt es auch die Möglichkeit, gezielt Spalten an- bzw. abzuwählen.
Sollten die Vorschläge also nicht passen, können die restlichen zumindest übertragen werden.
Das gezielte An- und Abwählen kann z.B. auch verwendet werden, um nachträglich neue Spalten einzufügen und das Suchen nach der gewünschten Quellspalte zu beschleunigen.

---

Ergebnisse aus vorherigen Spalten einfügen

Hier können Sie aus allen Werten, welche links der aktuellen Spalte stehen, wählen. D.h. Sie können einen bereits angepassten Wert wieder verwenden. Die Variablen einer Ergebnisspalte erkennen Sie am Ausdruck result wie z.B.

${result['preis']}

Klicken Sie hier, um ein Beispiel anzuzeigen

Ausgangslage:

Sie haben die selbe Quelldatei wie im obigen Beispiel und haben schon die oben beschriebene Spalte “preis” erstellt (EUR 99.95). Es existiert in der Quelldatei ebenfalls eine Spalte “versandkosten”.

Ziel:

Das Zielsystem erwartet eine Spalte “preis_+_versandkosten” mit Währung, Preis und Versandkosten. ( z.B. EUR 99.95 + 6.95 )

Vorgehen:

Legen Sie eine neue Spalte mit dem Titel “preis_+_versandkosten” hinter der Spalte “preis” an. Danach klicken Sie auf den ”+” Button neben dem Feld “Wert”. Gehen Sie in dem neuen Fenster auf den Reiter “aus Ergebnisspalte” und wählen die Spalte “preis” aus. Das Feld “Wert” ist nun mit ”${result[‘preis’]}” gefüllt. Nun haben Sie den identischen Wert aus der vorher selbst erstellten Spalte “preis”. Um die Versandkosten hinzuzufügen klicken Sie erneut auf ”+” und wählen die Quellspalte “versandkosten” aus. Abschließend fügen Sie das Trennzeichen ” + ” zwischen den beiden Spaltenwerten ein.

Somit ergibt sich als Resultat im Feld “Wert”: ${result[‘preis’]} + ${versandkosten}

---

Outputs vorheriger Steps einfügen

Sie haben die Möglichkeit Meta-Daten wie z.B. die aktuelle Zeit beim Ausführen des Flows (prop_actualruntime) oder den Zeitpunkt der letzten Ausführung des Flows (prop_lastruntime) in eine Spalte einzufügen. Dies ermöglicht Ihnen, hochdynamische Spalten zu erzeugen.

Klicken Sie hier, um ein Beispiel anzuzeigen

Ausgangslage:

Sie haben eine Quelldateien mit mehreren Spalten.

Ziel:

Das Zielsystem erwartet eine Spalte “uebertragen” mit den aktuellen Datum. (z.B. Feb 6, 2014 )

Vorgehen:

Legen Sie eine neue Spalte mit den Titel “uebertragen” an. Klicken Sie auf den ”+” Button und navigieren Sie in den auftauchenden Fenster auf den Reiter “Outputs vorheriger Steps”. Hier wählen Sie “prop.actualruntime” aus, danach wird das Feld “Wert” mit ${meta.prop_actualruntime!} gefüllt.

Da dieser Wert mehrere Informationen wie z.B. Zeit, Datum, Jahr etc. enthält, müssen Sie zum Schluss noch definieren, welchen Wert Sie benötigen. Fügen Sie dazu im Feld “Wert” hinter dem ”!” folgende Anweisung ein “?date” ein.

Somit ergibt das Resultat im Feld “Wert”: ${meta.prop_actualruntime!?date}

Achtung:

Bei jedem Datumswert muss definiert werden, was angezeigt werden soll. Dazu haben Sie folgende Optionen:

?date - liefert das Datum

?time - liefert die Zeit

?datetime - liefert das Datum gefolgt von der Zeit

Auf Relationen zugreifen

So wie es bei Datastores möglich ist, Relationen abzubilden (siehe Datastores#HierarchischeDaten), gibt es auch bei Spreadsheets, die aus einem Datastore kommen die Möglichkeit auf diese Relationen zuzugreifen.

Hinweis bei Verwendung von Filter und Mapper in Verbindung mit Relationen

Filter: Der Filter-Step ist der einzige Step, der Relationen für nachfolgende Steps erhält. Das funktioniert hier, weil der Filter die Zeilen des SearchDatastores direkt durchschleift. D.h. Steps nach einem Filter können noch auf die Relationen zugreifen.

Mapper: Der Zugriff auf die Relationen ist nur für den Mapper selbst möglich - sofern das Input-Spreadsheet noch die Relationen hat (SearchDatastore und Filter). Nach dem Mapper gehen diese Relationen aber verloren. D.h. weitere Steps, die den Output dieses Mappers konsumieren, haben keinen Zugriff mehr auf die Relationen. Das gleiche gilt für alle Steps, die Spreadsheets verarbeiten.

Mit anderen Worten: der Filter ist der einzige Steps, der Relationen erhält. Bei allen anderen Steps, sind die Relationen für nachfolgende Steps nicht mehr verfügbar.

Beispiele:

Step	Zugriff auf Relation möglich
SearchDatastore	-
Mapper	ja
Mapper	nein
weiterer Step	nein

Step	Zugriff auf Relation möglich
SearchDatastore	-
Filter	ja
Mapper	ja
Mapper	nein
weiterer Step	nein

Relationsarten

In Synesty Studio gibt es 2 Arten von hierarchischen Relationen: die sog. Parent-Variant und Master-Child Relation. Diese sind durch folgende Eigenschaften charakterisiert:

Relation 1: Parent - Variant 

• Parent und Variantenzeilen haben identische Spaltennamen

• Bei Datastores existieren Parent- und Variant-Zeilen in dem selben Datastore und im selben Folder

• Varianten werden beim Import in den Datastore über die Spalte parent_identifier mit der Parent-Datensatz verknüpft

Relation 2: Master - Child 

• Master-Zeilen und Children-Zeilen haben können unterschiedliche Spaltenname haben (da sie aus Datastores mit 2 unterschiedlichen Schemas kommen können)

• Bei Datastores existieren Master-Zeilen in einem Master-Datastore und Children in einem mit dem Master-Datastore verknüpften Child-Datastore

  • beide Datastores können unterschiedliche Schema verwenden - daher auch die unterschiedlichen Spaltennamen

• Children werden beim Import in den Datastore über die Spalten master_identifier, und master_datastore mit dem Master-Datensatz verknüpft 

Freemarker Ausdrücke

In diesem Zusammenhang sind folgende Freemarker-Ausdrücke relevant, die im nächsten Abschnitt beschrieben werden.

${parent['columnname']!} - greift auf eine Spalte der Parent-Zeile zu
${row.variants()!} - greift auf alle Varianten-Zeilen der aktuellen Parent-Zeile zu
<#if row.variants()??>Hat ${row.variants()?size} Varianten<#else>Hat 0 Varianten</#if>
<#if row.parent()??>ja, ist Variante, weil Parent vorhanden<#else>Nein, ist keine Variante, da kein Parent vorhanden</#if>

${master['columnname']!} - greift auf eine Spalte der Master-Zeile zu
${row.children()!} - greift auf alle Child-Zeilen der aktuellen Master-Zeile zu
<#if row.children()??>Hat ${row.children()?size} Child-Zeilen<#else>Hat 0 Child-Zeilen</#if>
<#if row.master()??>ja, ist Child-Zeile, weil Master vorhanden<#else>Nein, ist keine Child-Zeile, da kein Master vorhanden</#if>

Ergebnisse aus Parent-Zeile einfügen

Diese Funktion funktioniert nur bei 2-stufigen Spreadsheets wie z.B. bei Datastore-Artikel mit Varianten oder Aufträge mit Auftragspositionen. Diese Spreadsheets haben einen 2-stufigen Aufbau, bei dem die erste Zeile (die sog. Parent-Zeile) z.B. Auftragskopfdaten enthält und darauf folgende Zeilen die Auftragspositionen (die sog. Kind-Zeilen) enthalten.

Wenn man nun in den Auftrags-Positions-Zeilen (Varianten-Zeilen) Auftragskopfdaten (Parent-Zeile) anzeigen will, kann man das mit der ${parent[‘columnName’]} machen.

Hinweis:

Voraussetzung für diese Funktion ist ein Spreadsheet, in dem es Varianten-Zeilen gibt, die mit einer Parent-Zeile verknüpft sind.
Bisher unterstützen dies nur wenige Steps z.B. SearchDatastore, PlentyMarketsGetItemsBase, PlentyMarketsSearchOrders und PlentyMarketsGetReorders. Die meisten Spreadsheets sind hingegen eher flach, und haben nicht diese Parent-Child-Verknüpfung (z.B. aus einem SpreadsheetCSVReader).

Wenn ein Spreadsheet Parent-Child Zeilen besitzt, dann erkennen Sie dies im Mapper SpreadsheetMapper am Tab “aus Parent-Zeile” (siehe Screenshot rechts)

Klicken Sie hier, um ein Beispiel anzuzeigen

Ausgangslage:

Sie haben einen Flow, der Auftragsdaten aus plentymarkets holt. Diese Daten kommen in einem 2-stufigen Spreadsheet mit Auftragskopfdaten und Auftragspositionen.  

Ziel:

Sie wollen in den Positionszeilen die Felder aus der Liefer- und Rechnungsanschrift ausgeben. Diese Werte stehen aber nur in der Zeile des Auftragskopfes (Parent-Zeile).  

Vorgehen:

Klicken Sie in das Wert-Feld der Spalte, wo der Wert angezeigt werden soll und klicken sie auf den Plus-Button. Sie sollten das Tab “aus Parent-Zeile” mit allen Spalten sehen. Klicken Sie z.B. auf die Spalte “OrderCustomerAddressCity”.

Daraufhin sollte im Wert-Feld ${parent[“OrderCustomerAddressCity”]!} stehen. Da die Auftragszeile selbst keine Parent-Zeile hat, sollten sie das Wert Feld noch wie folgt abändern, damit keine Fehlermeldung erscheint.

<#if parent??>${parent["OrderCustomerAddressCity"]!}<#else>${OrderCustomerAddressCity}</#if>

Ergebnis:

In den Auftragspositionen stehen jetzt auch Daten aus der Parent-Zeile mit den Auftragskopfdaten.
 

Auf Varianten-Zeilen zugreifen

Hinweis

Diese Funktion steht nur bei Spreadsheets des Steps SearchDatastore zur Verfügung.

Wenn man Ergebnisse aus einem Datastore verarbeitet, der Parent- und Varianten Datensätze enthält, dann gibt es die Möglichkeit, innerhalb der Parent-Zeile auch auf die Varianten-Zeilen zuzugreifen.
Zum Beispiel kann man damit die Anzahl der Varianten-Zeilen prüfen oder in Abhängigkeit der Inhalte bestimmter Varianten-Zeilen in der Parent-Zeile reagieren.

Beispiel: Ausgabe in Parent-Zeile nur, wenn es mindestens eine Varianten-Zeile gibt

<#if (row.variants()?? && row.variants()?size > 0)>Diese Parentzeile hat ${row.variants()?size} Variantenzeilen<#else>Keine Variantenzeile vorhanden</#if>

Beispiel: In Parent-Zeile alle Varianten-Artikelnummern ausgeben

<#if (row.variants()?? && row.variants()?size > 0)>

  <#list row.variants() as v>
    ${v.get('artikelnummer')!} -
  </#list>

</#if>

In den meisten Fällen setzt man den Filter im SearchDatastore Parents/Varianten Filter=“Nur Parents”,damit die Varianten-Zeilen im Ausgabe-Spreadsheet erstmal ausgeblendet werden, man aber dann im Skript per row.variants() darauf zugreift und eine eigene Ausgabe erzeugt. 

Ergebnisse aus Master-Zeile

Analog zur Parent-Zeile gibt es die Möglichkeit auch auf den Master-Datensatz zuzugreifen. Ein Master-Datensatz gibt es allerdings nur im Kontext von Datastores, da es auch nur dort Master-Child-Beziehungen gibt.

Hinweis

Diese Funktion steht nur bei Spreadsheets des Steps SearchDatastore zur Verfügung.

Beispiel: Auf identifier-Spalte der Master-Zeile zugreifen

${master['identifier']!}

Auf Kind-Zeilen (children) zugreifen

Hinweis

Diese Funktion steht nur bei Spreadsheets des Steps SearchDatastore zur Verfügung.

Wenn man Ergebnisse aus einem Master-Datastore verarbeitet, der mit einem Child-Datastore verknüpft ist, dann gibt es die Möglichkeit innerhalb der Master-Zeile auch auf die Zeilen des Child-Datastores zuzugreifen, den sog. children.
Zum Beispiel kann man damit die Anzahl der Children prüfen oder in Abhängigkeit der Inhalte bestimmter Children in der Master-Zeile reagieren 

Beispiel: Ausgabe in Master-Zeile nur, wenn es mindestens eine Child-Zeile gibt

<#if (row.children()?? && row.children()?size > 0)>Diese Masterzeile hat ${row.children()?size} Children<#else>Keine Children vorhanden</#if>

Beispiel: In Master-Zeile alle Children-Artikelnummern ausgeben

<#if (row.children()?? && row.children()?size > 0)>

  <#list row.children() as c>
    ${c.get('artikelnummer')!} -
  </#list>

</#if>

In den meisten Fällen setzt man den Filter im SearchDatastore Children ausgeben=“Children nicht ausgeben”, damit die Children-Zeilen im Ausgabe-Spreadsheet erstmal ausgeblendet werden, man aber dann im Skript per row.children() darauf zugreift und eine eigene Ausgabe erzeugt.

Wert-Funktion einfügen

Zusätzlich zum Plus-Zeichen können sie über das -Symbol Skript-Funktionen einfügen. Die hier dargestellten Funktionen sind als Eingabehilfe anzusehen und erleichtern das etwas aufwändigere Tippen per Hand. In den meisten Fällen müssen Sie jedoch die eingefügten Funktionen noch auf ihre Spaltennamen anpassen, da lediglich Beispiele eingefügt werden. 

Diese Funktionen gliedern sich in drei Teile, wie man im Screenshot sieht. 

Freemarker Built-Ins

Freemarker Built-Ins sind Funktionen, die bereits im Kern in die Freemarker-Sprache integriert sind und auch in der offiziellen Freemarker-Dokumentation erklärt sind. Die aufgeführten Funktionen sind nur eine Auswahl der häufig verwendeten Funktionen und sind nicht vollständig. 

Hinweis

Mehr Informationen und Grundlagen zur Anwendung auch auf der Seite Scripting.

Funktion	Beschreibung	Beispiel
if else	Fügt eine einfache WENN-DANN Bedingung ein.	<#if column == “value1”>foo<#else>bar</#if>
if elseif else	Fügt eine erweiterte WENN-DANN Bedingung mit einer Abfrage für 3 Bedingungen ein.	<#if column == “value1”>foo<#elseif column == “value2”>foo2<#elseif column == “value3”>bar<#else></#if>
list	Beispiel-Code, um über eine Liste zu iterieren. Mehr zu sequences.	<#assign meineListe = “1,2,3,4”?split(”,”) /><#list meineListe as item>${item!}</#list>
replace	Ersetzt Teile einer Zeichenkette.	${meineSpalte!?replace("wort1","wort2")!} Ersetzt wort1 mit wort2.
number	Wandelt einen String (Text) in eine Zahl um. Wichtig: Es muss ein Punkt als Dezimaltrenner vorhanden sein.	${spalteMitZahl!?number + 5} Wandelt Wert einer Spalte in eine Zahl und addiert 5 darauf. Falls die Zahl noch keinen Punkt als Dezimaltrenner verwendet, dann ersetzen Sie erst das Komma durch einen Punkt: ${spalteMitZahl!?replace(",",".")?number + 5}
lowercase	Wandelt Text komplett in Kleinbuchstaben.	${column!?lower_case!}
uppercase	Wandelt Text komplett in Großbuchstaben.	${column!?upper_case!}
capitalize	Schreibt den ersten Buchstaben eines Wortes groß.	${column!?capitalize!}
trim	Entfernt führende und endende Leerzeichen.	${column!?trim!}
contains	Prüft ob ein Text eine Teilzeichenkette enthält.	<#if column!?contains(“substring”)>foo<#else>bar</#if>
index_of	Gibt die Position einer Teilzeichenkette in einem Text zurück.	${column!?index_of(“substring”)!}
last_index_of	Gibt die letzte Position einer Teilzeichenkette in einem Text zurück.	${column!?last_index_of(“substring”)!}

Template Funktionen

Diese Funktionen sind nicht Teil von Freemarker, sondern wurden von Synesty extra eingebaut. Es handelt sich um nützliche Helfer-Funktionen für einige Spezialfälle oder als Ersatz für fehlende Funktionen.
Sie können im Mapper über das Plus-Icon / Scripten / Template Funktionen erreicht werden.

 

Eine Übersicht und Erklärung aller Template-Funktionen mit Beispielen finden Sie hier:

• Übersicht aller Template-Funktionen

Spezialfunktionen

Auf der Seite zu Spreadsheet-Funktionen finden Sie einige Spezialfunktionen, die man im Mapper benutzen kann. Dort lernen Sie z.B. wie man auf die aktuelle Zeile als Objekt zuzugreifen kann oder wie man über alle Spalten iteriert und diese ggf. filtert.

Bedingungs-Generator

Im Abschnitt Freemarker-Build Ins (und auch im Abschnitt Scripting wurde erklärt, wie man WENN-DANN Bedingungen mit der Freemarker-Syntax formulieren kann. 
Leider ist das etwas schwerfällig, vor allem für neue Nutzer. 

Der Condition-Builder für WENN-DANN Bedingungen soll dieses Problem vereinfachen.

Im Funktionsmenü in jeder Spalte finden Sie jetzt das Tab “Bedingung generieren”. Mit diesem flexiblen Wizzard, können Sie sich Bedingungen zusammen klicken. Daraufhin wird das entsprechende Skript für die Bedingung generiert.

Wir empfehlen für WENN-DANN Logik immer zuerst mit dem Generator zu beginnen und danach die Bedingung zu editieren. In de Regel sollte der vom Generator erzeugte Code für die meisten Fälle ausreichend sein. Es kann aber sein, dass sie eine derart komplexe Bedingung formulieren wollen, so dass eine manuelle Nachbearbeitung notwendig ist. 

---

Daten

Hier werden die Daten der Spalte dargestellt. Diese dienen der Vorschau, sind nicht direkt editierbar und werden durch die Felder Quelle oder Wert sowie konfigurierten Funktionen definiert.

Visuelle Funktionen

Es stehen einige “visuelle Funktionen” zur Verfügung welche Ihnen dabei helfen können, dass Mapping (optisch) übersichtlicher und informativer zu gestalten. Das resultieren Output-Spreadsheet (also das Ergebnis des Mappings) bleibt davon unbetroffen.

Spalten farbig markieren

Sie haben die Möglichkeit jede Spalte des Mappers mit einer Farbe zu markieren. Dies kann z.B. dabei helfen wichtige oder zusammengehörige Spalten optisch einfacher ausmachen zu können.

Wenn Sie das Mapping mittels eines Steps vornehmen, werden die farbig markierten Spalten ebenfalls in der “mappingdefinition” des Steps farbig hervorgehoben

Spalten filtern

Hier haben Sie die Möglichkeit gezielt Spalten ein- bzw. auszublenden. Dies kann z.B. bei sehr großen Spreadsheets von Vorteil sein, bei denen aktuell nur bestimmte Spalten interessieren und nicht ständig hin und her gescrollt werden soll.

Durch Klick auf Spalten filtern, öffnet sich der Filter-Dialog.

• Suchbegriff: Es wird nach einem Wert in wahlweise Titel, Quelle oder Wertfeld gesucht.
  Es können diese Felder ebenfalls parallel durchsucht werden, siehe untere Checkbox Leiste
  
  Bei der Suche können optional folgende Modifikatoren verwendet werden:

  • * = Platzhalter
  • ^ = Wert beginnt mit
  • $ = Wert endet mit

• Funktionen: Es ebenfalls nach speziellen Funktionen gesucht werden. Hierbei kann ausgewählt werden ob mindestens eine Funktion gesetzt sein muss, oder nach speziellen Funktionen eingegrenzt werden.

Auf “Filter anwenden” klicken, um die aktuellen Filtereinstellungen auf das Mapping anzuwenden.

• Gefilterte Spalten: Die aktuell eingeblendeten Spalten mit einem Häkchen versehen. Es kann jederzeit durch Klick auf eine Checkbox jede Spalte ein- bzw. ausgeblendet werden. Trifft also z.B. eine Filtereinstellung nicht auf alle gewünschten Spalten zu, kann hier nachjustiert werden.

Der Spaltenfilter ist nicht destruktiv

Der Spaltenfilter ist nur ein visuelles Hilfsmittel des Mappers, welcher bei jedem neuladen des Mappings erneut eingestellt werden muss.
Wird also z.B. ein Filter angewandt der Spalten ausblendet und das Mapping anschließend gespeichert, werden die ausgeblendeten Spalten nicht gelöscht sondern ganz normal mitgespeichert.

Spalten kommentieren

Sie können mittels des Sprechblase-Icon beliebige Spalten kommentieren. Dies macht z.B. Sinn wenn Sie in der Spalte komplexe Skripte anwenden.

Wenn Sie das Mapping mittels eines Steps vornehmen, werden die kommentierten Spalten ebenfalls in der “mappingdefinition” des Steps angezeigt.

Spalte verschieben

Durch Klick auf einen der zwei Pfeile, können Spalten nach rechts bzw. links verschoben werden. 

Alternativ kann auch die Spalten verschiebne-Funktion benutzt werden, die bei vielen Spalten effektiver ist. Hier zu navigieren Sie zu Spalten → Spalten verschieben (Shortcut: CTRL + L)

Unter Spalten/Spalten verschieben können Sie alle Spalten schnell und einfach per Drag&Drop verschieben.

Hinweis

Durch klick auf das Fadenkreuz-Icon gelangen Sie nach dem Verschieben schnell direkt in eine gewünschte Spalte.

Spalte löschen

Ein Klick auf den “Mülleimer” entfernt eine Spalte aus dem SpreadSheet.

Einstellungen

Allgemeine Einstellungen

Gruppieren nach Spaltenname: Diese Option ermöglicht es nach einer Spalte des Spreadsheets zu Gruppieren. Weitere Informationen siehe Gruppieren/Aggregatfunktionen

Sortieren nach Spaltenname: Wählen Sie hier die Spalte aus, welche sortiert werden soll.

Sortieren: Absteigende oder Aufsteigende Sortierung

Anzahl der Zeilen in Vorschau: Dieser Wert legt fest wie viele Zeilen in der Vorschau des Spreadsheets angezeigt werden. Wählen Sie möglichst kleine Werte.  

Unsichtbare Zeichen anzeigen

Sie können sich auf Wunsch unsichtbare- sowie Steuerzeichen anzeigen lassen. Steuerzeichen landen erfahrungsgemäß vor allem durch Copy&Paste von Werten aus anderen Programmen im Mapper.

Einstellung wird gespeichert

Die aktuell gewählte Einstellung wird gespeichert. Das bedeutet, stellen Sie die Anzeige aller Zeichen an, wird diese auch in allen anderen Mappern und Codeareas angezeigt.

An folgenden Stellen werden dann im Mapper die unsichtbaren Zeichen angezeigt:

Wert Feld

Steuerzeichen werden als umgedrehte, rote Fragezeichen angezeigt. Hovern Sie mit der Maus über ein solches Zeichen, erscheinen weitere Informationen zu diesem.

Findet unser Automatismus ein solches Zeichen, wird zusätzlich noch ein Hinweis angezeigt. Im Zweifel prüfen Sie aber am besten noch einmal die entsprechende Spalte selbst nach.

Tabellenzellen

Die unsichtbaren Zeichen werden ebenfalls für Ihre aktuell in der Vorschau befindlichen Spaltenwerte angezeigt.

Code Editor Beim hovern mit der Maus über ein Steuerzeichen (im Code Editor die dunklen Badges), erfahren Sie weitere Informationen zum gefunden Zeichen.

Hinweis

Jeder andere Step der eine Codearea nutzt (z.B. der Step TextHTMLWriter), kann ebenfalls unsichtbare Zeichen anzeigen

Funktionen

Unter dem Menüpunkt “Funktionen” stehen Ihnen eine Vielzahl an vorgefertigten Operationen zum Anpassen Ihrer Daten zur Verfügung. Damit lassen sich schnell und einfach grundlegende Transformationen an Ihren Daten vornehmen.

Reihenfolge

Funktionen werden immer von oben nach unten abgearbeitet.

Suchen & Ersetzen

Diese Funktion erlaubt es Zeichen(ketten) zu ersetzen. Sie können beliebig viele Regeln durch Klick auf “Hinzufügen” definieren.

Hinweis

Sie können im Suchmuster auch einen sog. regulärer Ausdruck verwenden (engl. regular expressions), hierfür aktivieren Sie bitte die Checkbox.

---

Rechenoperation

Rechenoperationen eignen sich für Spalten mit numerischen Daten.

Folgende Rechenoperatoren stehen zur Verfügung:

• Addition +
• Subtraktion -
• Multiplikation *
• Division /

Dezimaltrenner

Bei mathematischen Funktionen wird immer ein Punkt als Dezimaltrenner erwartet. D.h. falls Zahlen mit Komma als Dezimaltrenner existieren, muss das Komma erst durch einen Punkt ersetzt werden. Eine Möglichkeit wäre dazu, die vorherige Suchen/Ersetzen Funktion zu benutzen oder im Wert-Feld mit Freemarker Komma durch Punkt zu ersetzen:

Beispiel: Komma durch Punkt mit Freemarker ersetzen

${OrderTotalGross?replace(",",".")?number + OrderShippingCosts?replace(",",".")?number}

---

Runden

Mit der Funktion Runden, haben Sie die Möglichkeit numerische Werte einer Spalte anzupassen.

• Runden - Die Runden Funktion ermöglicht die Rundung auf eine feste Anzahl von Nachkommastellen oder eine Rundung auf einen festen Rundungswert.

 

Nachfolgend finden sie einige Beispiele zu den verfügbaren Rundungsoperationen:

Achtung

Sie können bei der Rundungsfunktion entweder einen Rundungswert definieren oder auf die zu rundenden Stellen angeben. Wenn sie beide Möglichkeiten nutzen möchten, können sie mit (Zwischen-)Ergebnis Spalten arbeiten.

Ausgangswert	Rundungsmodus	Rundungswert	Stellen	Ergebnis
182.472	CEILING (Aufrunden)	0.9	-	182.9
182.472	CEILING	0.1	-	183.1
182.472	CEILING	5	-	185
182.472	CEILING	0	-	190
182.472	CEILING	00	-	200
182.472	CEILING	-	2	182.48
182.472	CEILING	-	1	182.5
182.472	CEILING	-	0	183
182.472	FLOOR (Abrunden)	0.9	-	181.9
182.472	FLOOR	0.1	-	182.1
182.472	FLOOR	5	-	175
182.472	FLOOR	0	-	180
182.472	FLOOR	00	-	100
182.472	FLOOR	-	2	182.47
182.472	FLOOR	-	1	182.4
182.472	FLOOR	-	0	182
182.472	HALF_UP (ab >= 5 aufrunden)	0.9	-	181.9
182.572	HALF_UP	0.9	-	182.9
182.472	HALF_UP	0.1	-	182.1
182.572	HALF_UP	0.1	-	183.1
182.472	HALF_UP	5	-	175
182.472	HALF_UP	0	-	180
182.472	HALF_UP	00	-	200
182.472	HALF_UP	-	2	182.47
182.475	HALF_UP	-	2	182.48
182.472	HALF_UP	-	1	182.5
182.472	HALF_UP	-	0	182
182.472	HALF_DOWN (ab > 5 aufrunden)	0.9	-	181.9
182.500	HALF_DOWN	0.9	-	181.9
182.572	HALF_DOWN	0.9	-	182.9
182.472	HALF_DOWN	0.1	-	182.1
182.672	HALF_DOWN	0.1	-	183.1
182.472	HALF_DOWN	5	-	175
182.472	HALF_DOWN	0	-	180
182.472	HALF_DOWN	00	-	200
182.472	HALF_DOWN	-	2	182.47
182.472	HALF_DOWN	-	1	182.5
182.472	HALF_DOWN	-	0	182
1.5	HALF_EVEN (bei ungerader Ganzzahl aufrunden, bei gerade abrunden)	0.9	-	1.9
2.5	HALF_EVEN	0.9	-	1.9
1.5	HALF_EVEN	-	1	1.5
2.5	HALF_EVEN	-	1	2.5

• Ganzzahl - diese Option führt dazu, das die Werte der Spalte auf eine Ganzzahl gerundet werden (entspricht “Abrunden, 0 Stellen”)

---

Datumsfunktionen

 

Geben Sie das vorhandene Quellformat und das gewünschte Zielformat an, um Datumswerte umzuformen.

Hinweis

Hier finden Sie Beispiele für die Umwandlung von Timestamps.

---

Querverweis

 

Mit einem Querverweis (in Excel auch bekannt als SVERWEIS) können Sie einen Wert aus einem Datastore anhand eines Schlüssels in ein Spreadsheet einfügen. Als Schlüssel zum “nachschlagen” kann eine der drei identifier-Spalten (identifier, identifier2, identifier3) verwendet werden.

Man kann einen Querverweis mit folgendem SQL Befehl vergleichen:

SELECT * FROM datastore WHERE datastorename = 'DemoDatastore' AND identifier = '123' AND folder = 'default';

• Datastore: Aus welchem Datastore sollen Daten abgerufen werden?

• Folder: Aus welchem Folder (Standard: ‘default’) sollen Daten abgerufen werden?

• Identifier / Identifier2 / identifier3: Um eine Zeile im Datastore zu identifizieren wird die Spalte identifier, identifier2 oder identifier3 genutzt.

• Rückgabewert bei Treffer: Geben Sie den Namen der Spalte (Field) an, aus der die Daten im Datastore geholt werden sollen.

• Standardwert: Hier können Sie einen Wert definieren, der zurückgegeben werden soll, wenn es keinen Treffer gibt (statt “No Record found”).

Video Tutorial

Ein Videotutorial zum Thema Querverweis findet man hier.

Hinweis zu identifier, identifier2 und identifier3

Füllen Sie nur ein einziges identifier-Feld aus. Sind mehrere identifier ausgefüllt, dann greift nur der erste “nicht leere” Wert.
Wünschen Sie eine Oder-Logik mit z.B. entweder identifier oder identifier2 dann empfehlen wir folgendes Cookbook.

Folder ignorieren

In einigen Fällen will man den Folder ignorieren. Klicken Sie dazu auf den +-Button und wählen “Folder beim Querverweis ignorieren”.
Das ist z.B. dann nützlich, wenn Sie in über mehrere Folder hinweg nach EAN suchen wollen, z.B. wenn Sie nicht genau wissen, in welchem Folder sich ein bestimmter Datensatz befindet.

Achtung bei doppelten Datensätzen

Sollte es Datensätze geben, die über mehrere Folder hinweg den gleichen identifier (oder identifier2 oder identifier3) besitzen, dann liefert der Querverweis nur den ersten gefundenen. Das Ergebnis ist in diesem Fall zufällig. Das sollten Sie beachten, wenn es ID-Dopplungen gibt.

Klicken Sie hier, um ein Beispiel anzuzeigen

Querverweis mit festem Wert

Fester Wert bedeutet hier, das wir ‘hart’ mit dem Wert 12345 einen Querverweis (manchmal auch Lookup genannt) auf die Identifier2-Spalte des DemoDatastore machen.
Über Datastore, Folder und Identifier / Identifier2 wird die entsprechende Zeile lokalisiert und über Field wird das auszugebende Feld ausgewählt. 

Querverweis mit dynamischen Wert aus aktueller Zeile

Dynamisch bedeutet in diesem Fall, dass anstatt eines festen ‘harten’ Wertes einen dynamisch Wert aus der jeweils aktuellen Zeile nutzt.
In diesem Beispiel wollen wir einen Querverweis immer über die aktuelle Spalte ‘identifier’ machen, um uns anhand dieser ID den Wert aus der entsprechenden Spalte im DemoDatastore zu holen.  

---

Mappingset

Mit einem Mappingset können Sie einen Quellwert in einen Zielwert übersetzen - sozusagen eine “Übersetzungstabelle”.Mappingsets werden im Mapper angewendet und finden sich unter den Funktionen in jeder Spalte.

Es gibt verschiedene Arten Mappingsets zu erzeugen:

• Default-Mappingset
• Mappingset Builder
• Datastore Mappingsets

Default-Mappingsets

Default-Mappingsets sind einfache Übersetzungstabellen, die manuell als Textblock gepflegt werden können.

Mappingset per Flow erweitern

Default-Mappingset können auch mit dem Step AddUpdateMappingset per Flow angelegt und automatisiert werden. Damit kann man die Pflege des Mappingsets auch automatisieren.

Mappingset Builder

Der Mappingset Builder ist ein Tool, mit dem man Mappingsets erstellen kann und zwar auf Basis von Daten in einem oder mehreren Datastores. Hier kann man die eindeutigen Werte einer gewählten Quellspalte auf erlaubte Zielwerte mappen. Die Zielwerte kommen ebenfalls aus einer Spalte eines Datastores.

Beispiel: Eigene Kategorien auf Google-Shopping Kategorien mappen

Erstellen Sie in neues Mappingset.

Wählen Sie den Mappingset-Typ Mappingset Builder:

Dadurch gelangen Sie in den Mappingset Builder.

Als Quelle wählen Sie ihren Datastore mit Artikeldaten, in dem es eine Kategorie-Spalte gibt, die Sie auf Google Shopping mappen wollen.
Als Ziel wählen Sie einen Datastore mit den Google Shopping Kategorien (dieses Cookbook zeigt am Beispiel, wie Sie diesen Datastore erstellen können).
Als Ziel-Spalte wählen Sie die Spalte, die den zu mappenden Zielwert enthält, z.B. die ID der Google-Shopping-Kategorie.
Als Ziel-Label (optional) können Sie eine Spalte auswählen, die eine sprechende textuelle Beschreibung der Ziel-Spalte enthält. Dies dient lediglich zu Anzeigezwecken und erleichtert den Mappingprozess.

Klicken Sie dann auf Konfiguration starten. Dadurch werden die Daten aus den Datastores gelesen und das Mapping gestartet.

Klicken Sie auf Mappingset speichern, wenn Sie fertig sind. Dadurch wird das Mappingset und die aktuelle Konfiguration gespeichert und das erstellte Mappingset kann genutzt werden.

Datastore Mappingsets

Datastore Mappingsets sind der neueste Mappingset Typ, bei dem das Mappingset über einen Datastore gepflegt wird. D.h. Schlüssel und Wert kommen aus jeweils einer Spalte eines Datastores (im Gegensatz zu den anderen beiden Mappingset-Typen, bei denen Sie die Schlüssel-Wert Paare selbst eingeben).

Das Mappingset kann dann genau wie die anderen Mappingsets im Mapper auf eine oder mehrere Spalten angewendet werden (siehe weiter unten Anwendung von Mappingsets).

Wann brauche ich Datastore Mappingsets?

Datastore Mappingsets sind dann sinnvoll, wenn man die Daten gern über einen Datastore pflegen möchte, bzw. schon einen Datastore hat, in dem zwei Spalten als Schlüssel- und Wertspalten für ein Mappingset in Betracht kommen.
Datastores sind in einigen Szenarien geeigneter, da man umfangreichere Import-Möglichkeiten hat und durch den Einsatz von Foldern quasi mehrere Mappingsets über einen zentralen Datastore abbilden kann.

 

Anwendung von Mappingsets

Es gibt zwei Arten der Anwendung von Mappingsets:

• einfache Mappingsets (d.h. einfache Übersetzung von Quell-Wert zu Ziel-Wert)

• Bereichs-Mappingsets (Zuweisung eines Quell-Bereichs zu einem Ziel-Wert z.B. “alle Preise zwischen 0 und 100 EUR bekommen 10% Rabatt”)

Wichtig:

Der Quellwert ist immer der aktuell sichtbare Wert der Spalte.  

Einfaches Mappingset

Ein einfaches Mappingset ersetzt den aktuellen Wert in einen Zielwert.

SucheBegriff1=ErsetzeDurch1
SucheBegriff2=ErsetzeDurch2
SucheBegriff3=ErsetzeDurch3

Funktionierendes Beispiel	Nicht funktionierendes Beispiel
Hier ist der Wert “SucheBegriff1”. Da dieser Wert auch im Mappingset auftaucht, greift die Übersetzung. Der neue übersetzte Wert ist “ErsetzeDurch1”.	In diesem Beispiel klappt die Übersetzung nicht, weil vor “SucheBegriff1” noch etwas anderes steht (im Beispiel Prefix”). Dadurch wird im Mappingset kein passender Eintrag gefunden, und es wird der unübersetzte Orginalwert ausgegeben (siehe Mapping-Modus weiter unten, um dieses Verhalten zu ändern).

Mehrere Werte in einer Zeile

Es ist auch möglich mehrere Werte in einer Zeile zu definieren. Das kann die Datenpflege erleichtern.
Dazu müssen die Werte auf der linken Seite des Gleichheitszeichens in doppelte eckige Klammern gesetzt werden und komma-getrennt eingegeben werden.

Beispiel - Farbübersetzungen

[[inkarnat, cherry, petrol]]=rot
[[lava, rust, mandarine, aprikot]]=orange

In diesem Beispiel werden verschiedene Farbvarianten für rot und orange definiert.

Hinweis

Es handelt sich hierbei lediglich um eine Kurzschreibweise. Die Werte innerhalb der eckigen Klammern werden im Hintergrund automatisch expandiert und in ein normales Mappingset übersetzt.  

Bereichs-Mappingset

Ein Bereichs-Mappingset hingegen funktioniert für Zahlenwerte und ermöglicht es verschiedene Zahlenbereich zu definieren. Der aktuelle Wert wird dann auf den Zielwert des entsprechenden Bereichs gemappt, zu dem er gehört.

1-100=bis 100
100.01-1000=groesser Hundert
1000.01-10000=groesser Tausend

Um Bereichs-Mappingsets zu nutzen, muss die Option Dieses Mappingset beinhaltet Bereiche angekreuzt werden (siehe 2. Screenshot).

Anwendungsbereiche:
Wenn man eine Preiskalkulation erstellt, dann will man oft bestimmte Regeln auf bestimmte Preisbereiche anwenden. z.B. sind manche Aufpreise nur für bestimmte Preisregionen sinnvoll, für andere aber nicht.
Durch Verwendung der Funktion Ergebnisse aus vorherigen Spalten einfügen ergeben sich sehr flexible Möglichkeiten individuelle WENN-DANN-Logik auf verschiedene Preisbereiche anzuwenden (siehe Beispiel).

+Ohne Bereichs-Mappingsets sähe die Logik wesentlich komplizierter und unübersichtlicher aus, da alle Bereichsprüfungen im Skript gemacht werden müssten. Jetzt ist nur noch das absolute Minimum notwendig. Vorstellbar wäre auch, dass man die Preisbereiche direkt auf Aufpreis-Faktoren mappt und diese direkt in weiteren Spalten zum kalkulieren verwendet. Damit sähe das ganze noch einfacher aus. Wie immer, hängt die Umsetzung von den konkreten Anforderungen ab. 

Beispiel: Einfaches Mappingset	Beispiel: Bereichs-Mappingset

Modus 1 mit Mappingset Name:

Sie können ein vorhandenes Mapping Set wählen oder ein neues erstellen, welches Sie über Datastores / Mappingset getrennt pflegen können.
Wann zu verwenden: Dieser Modus empfiehlt sich, wenn sie das gleiche Mapping Set mehrmals z.B. in verschiedenen Spalten oder verschiedenen Flows wiederverwenden wollen. Dann sparen sie sich Arbeit, da das Mapping Set an einer zentralen Stelle gepflegt werden kann.

Modus 2 direkt über Textfeld “Mappingset String”:

Das ist die schnelle Variante, wenn sie ein Mapping Set nur in einer einzigen Spalte brauchen und nicht an anderer Stelle wiederverwenden wollen.

Bei beiden Methoden wird dabei der zu suchende Begriff und der neue Wert durch ein = getrennt. Es können beliebig viele dieser sogenannten Key=Value Paare gebildet und getrennt durch “Enter” angelegt werden

Achtung

Wir empfehlen Ihnen ein Mappingset zu erstellen. Dieses kann zentral außerhalb des Flows nachgepflegt werden und auch in anderen Flows wiederverwendet werden.

Konfiguration

Mapping Modus:

Über den Mapping Modus kann man das Verhalten beeinflussen, wie sich die Übersetzung auswirkt.

Hinweis

Der Mapping Modus funktioniert nur für normale Mappingsets und  nicht für Bereichs-Mappingsets.

• Originalwerte ausgeben (Keep Original Values) - Bedeutet, dass die Originalwerte ausgegeben werden, sollte das Mapping Set keinen zu mappenden Wert enthalten.

• Nicht gemappte Werte entfernen (Remove unmapped original values) - Bedeutet, dass ein leerer Wert ausgegeben wird, sollte das Mapping Set keinen zu mappenden Wert enthalten.

• Nicht gemappte Werte präfixen (Mark unmapped original values) - Bedeutet, dass die Originalwerte mit dem Prefix NO_MAPPING ausgegeben werden z.B. “NO_MAPPING 1234”. D.h. man kann damit ungemappte Werte besser erkennen und z.B. durch Filter gezielt diese Zeilen lokalisieren.

• Standardwert benutzen - Bedeutet, dass die Originalwerte durch einen Standardwert ersetzt werden. Somit können Werte, welche nicht im Mapping Set enthalten sind, durch ein festgegebenen Wert überschrieben werden.

• Suchen & Ersetzen (case-sensitive) - Bedeutet, dass jeder Eintrag des Mappingsets im Sinne einer Suchen&Ersetzen-Funktion auf den aktuellen Wert angewendet wird. Case-sensitive bedeutet, dass Groß/-Kleinschreibung der Mappingset-Einträge beachtet wird.

• Suchen & Ersetzen (ignore case) - Bedeutet, dass jeder Eintrag des Mappingsets im Sinne einer Suchen&Ersetzen-Funktion auf den aktuellen Wert angewendet wird. Ignore-case bedeutet, dass Groß/-Kleinschreibung der Mappingset-Einträge keine Rolle spielt.

• Suchen & Ersetzen (Regulärer Ausdruck) - Bedeutet, dass jeder Eintrag des Mappingsets im Sinne einer Suchen&Ersetzen-Funktion auf den aktuellen Wert angewendet wird. Jeder Quellwert des Mappingsets entspricht damit einem sog. regulären Ausdruck (engl. regular expression). Damit lassen sich sehr komplexe Suchmuster realisieren. Diese Funktion ist aus Performance-Sicht am langsamsten. Bitte nur verwenden, wenn Sie wissen was sie tun.

• Mappe, wenn Wert enthält […] (case-sensitiv) - Bedeutet, dass jeder Eintrag des Mappingsets im Sinne einer Suchen&Ersetzen-Funktion auf den aktuellen Wert angewendet wird. Jeder Quellwert wird überprüft ob der gesuchte Wert vorhanden ist. Diese Funktion erlaubt Ihnen Texte zu ersetzen, auch wenn Ihnen der genaue Inhalt des zu ersetzenden Textes oder Wertes nicht bekannt ist. Case-sensitive bedeutet, dass Groß/-Kleinschreibung der Mappingset-Einträge beachtet wird.

• Mappe, wenn Wert enthält […] (ignore case) - Bedeutet, dass jeder Eintrag des Mappingsets im Sinne einer Suchen&Ersetzen-Funktion auf den aktuellen Wert angewendet wird. Jeder Quellwert wird überprüft ob der gesuchte Wert vorhanden ist. Diese Funktion erlaubt Ihnen Texte zu ersetzen auch wenn Ihnen der genaue Inhalt des zu ersetzenden Textes/Wertes nicht bekannt ist. Ignore Case bedeutet, dass Groß/-Kleinschreibung der Mappingset-Einträge nicht beachtet wird.

Hinweis

Grundlage für die Übersetzung ist immer der komplette aktuelle!!! Wert der Zelle.
Ausnahme: Mapping-Modus Suchen & Ersetzen: Bei Suchen & Ersetzen wird jeder Eintrag des Mappingsets nacheinander auf den kompletten Wert der Zelle angewendet.

Beispiel: Suchen & Ersetzen (case-sensitive)

Spaltenwert: Das ist ein sehr langer Beschreibungstext. 

Mappingset:

ist=1
langer=bla
text=foo

Spaltenwert nach Anwendung des Mappingsets: Das 1 ein sehr bla Beschreibungsfoo. 

• Trennzeichen (Source Delimiter): Diese Option ermöglicht es einzelne Werte einer Liste zu Mappen 

Beispiel:

Werte in einer Spalte sind durch > getrennt. Z.B.: kat1>kat2>kat3

Mappingset:

kat1=101
kat2=102
kat3=105

Ergebnis mit Trennzeichen ”>”:

101>102>105

• Duplikate entfernen(Remove Duplicates): Ist diese Option aktiviert werden mehrfach vorkommende Werte im Ergebnis des Mappings entfernt

Beispiel:

Werte in einer Spalte sind durch > getrennt. Z.B.: A,B,C,Y

Mappingset:

A=101
B=102
C=105
Y=102

Ergebnis mit Trennzeichen ”,” und Duplikate entfernen : 101,102,105

---

Text Funktionen

Diese Funktionen sind nützlich, um Texten und Strings den letzten Schliff zu geben, ohne dass man skripten muss.

Leerzeichen und Zeilenumbrüche

Diese Funktion entfernt Leerzeichen am Anfang und Ende der Spalten (sog. Trimmen) oder Zeilenumbrüche. Man kann zwischen 3 Optionen wählen:

• Trimmen und Zeilenumbrüche durch Leerzeichen ersetzen
• Trimmen und Zeilenumbrüche entfernen
• nur Trimmen (Zeilenumbrüche erhalten)

Auftrennen

Damit kann man einen Spaltenwert nach einem bestimmten Zeichen trennen und dann auf einen bestimmten Teil zugreifen. Häufig braucht man das bei Komma-separierten Listen, um z.B. auf das 2. Element zuzugreifen.

• Trennzeichen - das Zeichen nach dem getrennt werden soll z.B. Komma oder Semikolon
• Position - das n-te Element auf das sie nach der Trennung zugreifen wollen. (0=das erste Element, 1=das zweite, 2=das dritte …)
  • statt einer Zahl kann man bei Position auch last oder first eingeben, um auf das letzte bzw. auf das erste Element zuzugreifen.
  • bei last gibt es auch die Möglichkeit, die Position relativ zum letzten Element zu bestimmen (z.B. zur Bestimmung des vorletzten Elements kann man schreiben last-1)

Beispiel:

Ausgangswert: Wort1,Wort2,Wort3
Trennzeichen: , (Komma)
Position: 1 
Ergebnis: Wort2 

Ausgangswert: Wort1,Wort2,Wort3
Trennzeichen: , (Komma)
Position: last 
Ergebnis: Wort3

Ausgangswert: Wort1,Wort2,Wort3
Trennzeichen: , (Komma)
Position: first 
Ergebnis: Wort1 

Ausgangswert: Wort1,Wort2,Wort3Trennzeichen: , (Komma)Position: last-1 Ergebnis: Wort2 

Teilzeichenfolge (engl. Substring)

Häufig muss man Zeichenketten/Strings auf eine bestimmte Länge kürzen, oder man braucht nur einen Teil davon. Dabei hilft diese Funktion, ohne das man Freemarker-Skripte benutzen muss. Der Vorteil dieser Positionen gegenüber der Freemarker-Skriptvariante ist, dass diese Funktion fehlertoleranter ist und man z.B. keine Längenprüfung machen muss.

Die zurückgegebene Teilzeichenfolge beginnt mit dem Zeichen der Startposition (Startposition am Anfang ist immer 0) und endet vor der angegeben Endposition.

Die Start oder Endposition kann auch leer gelassen werden (siehe Beispiele unten).

Beispiel: 

Ausgangswert: Synesty Studio
Startposition: 0
Endposition:  5
Ergebnis: Synes

Ausgangswert: Synesty Studio
Startposition: 3
Endposition:  6
Ergebnis: est

Ausgangswert: Synesty Studio
Startposition: 3
Endposition:  
Ergebnis: esty Studio

Ausgangswert: Synesty Studio
Startposition: leer
Endposition:  6
Ergebnis: Synest

Skript

Das Feld Skript gleicht dem Feld “Wert”. Auch hier können Sie, per Freemarker, auf alle Quellspalten und Meta-Daten zugreifen.

Der Unterschied liegt darin, dass das Skript ganz am Ende der Verarbeitungskette ausgeführt wird. So können Sie beispielsweise eine Spalte “oben” im Wertfeld manipulieren und diese manipulierten Daten im Skript Feld per ${_currentValue!} nochmals transformieren. In einigen Fällen benötigen Sie diese Flexibilität.

Hinweis

Hier finden Sie einige Beispiele zum Feld “Wert” und “Skript”.

Gruppieren/Aggregatfunktionen

Diese Funktion ermöglicht es eine Spalte eines Spreadsheets zu gruppieren. Um die Funktion zu nutzen wählen Sie unter “Einstellungen” -> “Gruppieren nach Spaltenname” den Titel der Spalte aus, welche gruppiert werden soll. Die Gruppierung bewirkt, das alle Zeilen mit gleichem Wert in einer Zeile zusammengefasst werden. 

Beispiel:

Nicht gruppierte Daten

Sie haben beim Gruppieren drei Modi zur Auswahl

A) Ergebnis nach Gruppierung nach 1.Spalte - Modus: Nur gruppierte Zeilen zeigen

Dieser Modus gibt als Ergebnis die Gruppierten Spalten aus. Die originalen Zeilen werden also “zusammengefasst” und nicht mehr einzeln dargestellt:

B) Ergebnis nach Gruppierung nach 1.Spalte - Modus: Ergebnis als unterste Zeile

Wählen Sie diesen Modus, um die originalen Zeilen zu erhalten und zusätzlich das gruppierte Ergebnis zusätzlich hinzuzufügen. Zu Illustrationszwecken wurden auf die 2. und 3. Spalte Aggregatfunktionen angewandt. Mehr dazu im nächsten Abschnitt. 

C) Ergebnis nach Gruppierung nach 1.Spalte - Modus: Ergebnis als oberste Zeile

Dieser Modus gleicht dem Modus aus B) nur das die Zeile anstatt unterhalb, oberhalb der zusammengehörenden Zeilen ausgegeben wird.

Aggregatfunktion

• Konfigurierte Standard Funktion

Über Einstellungen / Gruppieren / Standard Aggregatfunktion kann die Aggregatfunktion gewählt werden, welche greift, wenn in einer Spalte “Konfigurierte Standard Funktion” eingestellt ist. Wählt man in der Spalte direkt eine andere Funktion, dann greift entsprechend die Konfiguration der Spalte. (Spalte hat Vorrang vor Standard-Funktion). Die Standard-Aggregat Funktion greift auch für alle „unbekannten Spalten“, die durch passThroughMode durchgeschliffen werden (sprich, die erst zur Ausführung bekannt werden).

• Wert der ersten Zeile (Standard): In dieser Spalte wird der Wert der ersten Zeile übernommen. Die Werte der restlichen gruppierten Zeilen gehen somit verloren.
• Erster nicht leerer Wert: Gibt den Wert der ersten Zeile, in der die Spalte nicht leer ist. 
• Wert der letzten Zeile: In dieser Spalte wird der Wert der letzten Zeile übernommen. Die Werte der restlichen gruppierten Zeilen gehen somit verloren.
• Alle Werte auflisten: Die Werte aller gruppierten Zeilen dieser Spalten werden als neuer Wert aufgelistet. Das Trennzeichen kann genutzt werden, um die Werte voneinander abzugrenzen

• Eindeutige Werte auflisten: Die unterschiedlichen Werte aller gruppierten Zeilen dieser Spalten werden als neuer Wert aufgelistet. Das Trennzeichen kann genutzt werden, um die Werte voneinander abzugrenzen
• Zeilen zählen: Anzahl aller gruppierten Zeilen (auch mit leeren Werten).
• Eindeutige Werte zählen (nicht-leer): Anzahl der eindeutigen Wert mit nicht leeren Werten.

Mathematische Aggregatfunktionen

Voraussetzung für eine sinnvolle Anwendung dieser Aggregatfunktionen ist, dass die Werte der Spalte in Form von Fließkommazahlen mit Punkt als Dezimaltrennzeichen vorliegen z.B. 1.28

• Kleinster Wert: Der niedrigste Wert aller gruppierten Zeilen wird ausgegeben.

• Größter Wert: Der höchste Wert aller gruppierten Zeilen wird ausgegeben.

• Summer aller Werte: Die Summe aller gruppierten Zeilen wird ausgegeben.

• Durchschnittswert: Der Durchschnitt aller gruppierten Zeilen wird ausgegeben (entspricht “Summe aller Wert” geteilt durch “Zeilen Zählen”).

Helferlein

Es stehen einige Optionen zur Verfügung um Funktionen effizient auf mehrere Spalten zu übetragen bzw. diese zu entfernen:

Für alle Funktionen dieser Spalte

• Alle Funktionen dieser Spalte in eine andere Spalte kopieren: Hiermit ist es möglich jegliche Funktionen einer Spalte in andere zu übertragen. Sobald die Funktionen kopiert wurden, taucht an allen anderen Spalten ein Symbol zum Einfügen auf. Bestehende Funktionen werden dabei überschrieben.

• Alle Funktionen dieser Spalte entfernen: Entfernt alle Funktionen.

Pro einzelner Funktion

• Diese Funktion anzeigen: Funktion wird in allen Spalten (links/rechts) von der aktuellen Spalte aufgeklappt
• Diese Funktion ausblenden: Funktion wird in allen Spalten (links/rechts) von der aktuellen Spalte zugeklappt
• Den Wert dieser Funktion übernehmen: Funktion wird in allen Spalten (links/rechts) von der aktuellen Spalte übernommen (bereits bestehende Werte werden überschrieben)

Ziel-Schema laden

Im Mapper kann man ein Zielschema laden. D.h., dass man ein fertiges Set von benötigten Spalten laden kann. Dabei kann man ein bestehendes Schema (siehe Datastores / Schema) auswählen, und dessen Spalten in das aktuelle Mapping laden. Alle Spalten werden daraufhin gelöscht und mit den Spalten des Schemas ersetzt.

Wann brauche ich das?

• wenn Sie Daten per Flow in einen Datastore importieren wollen. 
  • Dazu laden Sie das Schema ihres Ziel-Datastores und kreuzen noch die Option “Identifier Spalten für Datastore Import hinzufügen” an.
• oder wenn man bestimmte Zielformate häufig braucht. Dann kann man dafür ein Schema anlegen, und dieses dann immer wieder bei Bedarf laden. 

Erlaubte Werte

Eine Eigenschaft von Schemas ist, dass man sog. “erlaubte Werte” hinterlegen kann (z.B. die Werte Neu oder gebraucht beim Feld Zustand). Diese tauchen dann dann auch in der Mappingansicht im Mapper auf, wenn man dieses Schema geladen hat. 
Einige Add-Ons bringen feste Schemas mit, wo diese erlaubten Werte bereits hinterlegt sind. 

${datecalc(prop_lastruntime?datetime, "DAY", -2)?string('yyyy-MM-dd HH:mm')}

Einfacher Zugriff auf erste Zeile eines Spreadsheets

Für fortgeschritte Nutzer, die z.B. oft direkt mit REST-APIs oder Webservices arbeiten, gibt es jetzt eine einfachere Möglichkeit per Freemarker auf Werte der ersten Zeile eines Spreadsheets zuzugreifen. 

Diese Funktion ist im Kontext von folgenden Steps interessant:

• TextHTMLWriter

• SpreadsheetUrlDownload , URLDownload und APICall (meistens um den HTTP-RequestBody zu erzeugen)

Wert der Spalte "status" der ersten Zeile: ${output@SpreadsheetUrlDownload_2.firstRow("status")!}

Hier wird der Wert der Spalte status der ersten Zeile des Spreadsheets ausgegeben. 

bzw.

Wert der Spalte "status" der ersten Zeile: ${output@SpreadsheetUrlDownload_2.firstRow("status", "no status")!}

Hier wird auch der Wert ausgegeben. Über den zweiten Parameter kann aber ein Default-Wert mitgegeben werden, der zurückgegeben werden soll, sollte es die Spalte Status nicht geben.

Hinweis zu Variablennamen

Der Variablenname output@SpreadsheetUrlDownload_2 ist nur ein Beispiel. Die Zahl am Ende (in diesem Fall _2) und unterscheidet sich je nach Step und Position des Steps. Über den Pfeil unter den Steps kommen Sie an den korrekten Variablenname.

Hinweis zum Unterschied von Variablennamen im Mapper und anderen Steps:

Es ist wichtig, dass man Variablen immer mit dem Plus-Button einfügt. Denn im Mapper SpreadsheetMapper unterscheidet sich die Schreibweise von Variablen, z.B. im Vergleich zum TextHTMLWriter Step. Beim Mapper steht bei Variablen, die aus vorherigen Steps oder Flow-Variablen kommen noch das Prefix “meta.”. Im TextHTMLWriter ist diese Prefix hingegen nicht notwendig. Der Plus-Button beachtet diese Dinge und fügt immer kontext-abhängig den korrekten Variablennamen ein - also mit- oder ohne .meta. 

und dann 

Wozu dient das meta-Prefix?

Durch das Prefix “meta.” werden Namenskollisionen verhindert und zwar zwischen Quellspalten und Flow-Variablen. Im Mapper kann man auf eine Quellspalte direkt per Spaltenname zugreifen. Flow-Variablen sind ebenfalls direkt durch ihren Namen verfügbar. Würde es nun eine Flow-Variable und eine Quell-Spalte mit gleichem Namen geben, würden diese sich gegenseitig überschreiben. Durch das “meta.” Prefix wird dies verhindert. Spaltennamen sind direkt ohne Prefix zugreifbar, und Flow-Variablen sowie Outputs vorheriger Steps mit “meta.”. Ein ähnliches Konzept gibt es auch im SpreadsheetUrlDownload.