DatastoreWriter Step
Der DatastoreWriter kann ein Spreadsheet, also tabellarische Daten, in einen Datastore importieren. Dabei kann man wählen ob man nur neue Datensätze einfügen, nur vorhandene aktualisieren oder beides gleichzeitig machen will.
Outputs
Der Step gibt mehrere Outputs als Spreadsheet zurück:
- neu eingefügten Datensätze,
- die aktualisierten (vorhandenen) Datensätze (egal ob inhaltliche Änderung oder nicht)
- die aktualisierten (vorhandenen) Datensätze mit Inhaltsänderung (bei denen sich mindestens ein Feld inhaltlich geändert hat)
- und die nicht angefassten Datensätze (Datensätze, die im Datastore vorhanden sind, aber nicht (mehr) im zu importierenden Spreadsheet).
Mit diesem Output-Spreadsheets kann man gezielt bestimmte Daten für Folgeprozesse verwenden. Zum Beispiel kann man alle Datensätze, die sich inhaltlich geändert haben (siehe Output "aktualisierten (vorhandenen) Datensätze mit Inhaltsänderung") in eine Datei schreiben und exportieren.
Schema automatisch erweitern
Datastore und Schema anlegen / erweitern
Wenn der Datastore vor dem Import noch nicht existiert, dann wird dieser automatisch zusammen mit einem Schema angelegt. Das Schema bekommt dann automatisch alle Spalten des zu importierenden Spreadsheets. Über die Option autoExtendSchema kann das Schema automatisch erweitert werden, sobald neue Spalten im Spreadsheet dazu kommen.
Einsatzgebiete
Der Step DatastoreWriter befindet sich meist am Ende eines Flows bzw. nach einem SpreadsheetMapper, wenn die Daten schlussendlich gespeichert werden sollen. Ein typischer Flow sieht ungefähr so aus:
Einfacher Import
Damit etwas importiert werden kann, muss das Spreadsheet mindestens über folgende zwei Spalten verfügen (siehe Datastores):
- identifier
- folder (optional: wenn leer wird automatisch "default" gesetzt)
Schreibweise beachten
Achten Sie darauf, dass die beiden Spalten exakt so geschrieben werden (alles Kleinbuchstaben).
Über diese zwei Spalten wird jeder Datensatz eindeutig identifiziert. Vorstellen kann man sich das mit Verzeichnissen und Dateien in einem Dateisystem.
Folder entspricht einem Verzeichnis und identifier entspricht der Datei.
Ein identifier darf pro folder nur 1x verwendet werden. Ansonsten gibt es einen Fehler. Mit anderen Worten: Ein Datensatz ist eindeutig durch folder + identifier.
Es gibt zwei Varianten, wie man dem Importer diese Spalten mitteilen kann.
Spaltenbezeichnung bereits im Spreadsheet vorhanden
Wenn das zu importierende Spreadsheet min. zwei Spalten mit diesen Spaltenname (identifier, folder) hat, dann kann das Spreadsheet importiert werden.
Sollte das Spreadsheet diese Spalten noch nicht haben, könnte man mit dem Mapper SpreadsheetMapper dieser Spalte erzeugen.
identifier-Spalten manuell definieren
Alternativ kann man bei der Konfiguration des DatastoreWriter auch angeben, in welchen Spalten sich identifier und folder befinden.
Potentielle Fehlerquellen und Fehlermeldungen
Achtung
Es dürfen dort nur die Spalten namen des Input-Spreadsheets eingetragen werden, die jeweils den identifier bzw. den folder beinhalten. Sie können identifierColum und folderColumn auch leer lassen, allerdings muss dann das Input-Spreadsheet die beiden Spalten identifier und folder haben.
Bitte achten Sie darauf, dass Sie nicht fälschlicherweise den Name eines Datastore folders bei folderColumn eintragen.
Achtung
Sollte das zu importierende Spreadsheet keine identifier-Spalte haben (z.B. weil Sie vergessen haben eine zu definieren), dann bricht der Flow mit Fehlermeldung ab:
Fall 1:No 'Artikelnummer' column in Spreadsheet. This column should be present and filled with a unique identifier of the record (e.g. productID).
- hier wurde identifierColumn=Artikelnummer definiert, aber das Spreadsheet hat gar keine Spalte mit dem Namen Artikelnummer
- Lösung: fügen Sie dem Spreadsheet eine Spalte mit dem Namen 'Artikelnummer' hinzu, oder korrigieren Sie den Wert von identifierColumn
Fall 2: No 'identifier' column in Spreadsheet. This column should be present and filled with a unique identifier of the record (e.g. productID).
- hier wurde identifierColumn vermutlich leer gelassen, weshalb der Import eine Spalte mit dem Namen 'identifier' erwartet. Diese scheint im Spreadsheet aber nicht vorhanden zu sein.
- Lösung:
- a) fügen Sie dem Input-Spreadsheet eine Spalte mit dem Namen 'identifier' hinzu,
- b) oder: definieren Sie per identifierColumn eine Spalte, die einen eindeutigen identifier enthält (z.B. eine EAN)
- falls Sie eine Mappingdefinition direkt im DatastoreWriter Step definiert haben (z.B. einmal auf Configure gedrückt), dann wird die Spalte darin erwartet. Ansonsten muss die Spalte im Input-Spreadsheet vorhanden sein.
Erweiterter Import
Der DatastoreWriter bietet noch weitere Optionen, um komplexere Import-Szenarien abzubilden.
Identifier2 Spalte
Jeder Datensatz in einem Datastores verfügt über eine identifier2 Spalte. Diese Spalte kann mit einer weiteren ID gefüllt werden. Diesen identifier2 kann man später für Querverweise benutzen.
identifier2 nicht eindeutig
Wichtig: Der identifier2 muss nicht eindeutig sein. D.h. er kann doppelt vergeben werden. Sie müssen selbst darauf achten, dass dieser eindeutig ist. Ansonsten kann es bei Querverweisen zu Fehlern kommen.
Es gibt wieder 2 Varianten, wie die identifier2 Spalte definiert werden kann:
- Spalten identifier2 bereits im Spreadsheet vorhanden
- oder Sie geben über das Inputfeld identifier2Column den Spaltennamen an, der den identifier2 enthält.
Achtung
Bitte achten Sie auch hier wieder darauf, dass Sie hier Spaltennamen eingeben und nicht fälschlicherweise den Name eines Datastore folders bei folderColumn eintragen.
Import von hierarchischen Spreadsheets (Parent - Variant innerhalb des gleichen Datastores)
Es besteht die Möglichkeit auch 2-stufige Daten in einen Datastore zu importieren. Das bedeutet, dass es eine Eltern-Zeile (Parent) und dazugehörige Varianten-Zeilen gibt. Man kennt das z.B. bei Produktkatalogen mit Hauptartikel - Artikelvarianten oder bei Rechnungen mit Rechnungskopf - Rechnungspositionen.
Dazu muss im Import-Spreadsheet eine weitere Spalte mit dem Namen parent_identifier eingefügt werden.
Diese Spalte muss mit dem identifier der Parent-Zeile gefüllt werden wie z.B.:
identifier | folder | parent_identifier |
---|---|---|
1 | default | |
1a | default | 1 |
1b | default | 1 |
Die Daten werden daraufhin in den Datastore importiert. Die Variant-Datensätze sollten dann an den entsprechenden Parent-Datensätzen hängen.
Wenn der Import korrekt funktioniert hat, dann sollten das in der Datastore-Suche wie folgt aussehen:
Hinweis
Datensätze mit Parent-Variant Beziehung basieren auf der Annahme, dass Parent-Datensatz und Variant-Datensatz im gleichen Datastore und im gleichen Folder liegen.
Inputs
Das sind die Optionen, mit denen man den Step konfigurieren kann.
Name | Datentyp | Beschreibung | Pflichtfeld | Werte |
---|---|---|---|---|
input | SPREADSHEET | Quell-Spreadsheet mit den zu importierenden Daten. | Ja | |
datastoreName | DATASTORE | Name des Ziel-Datastores. Wenn der Datastore noch nicht existiert, wird dieser zusammen mit einem Schema neu erstellt. Das Schema erhält automatisch die Spalten des Quell-Spreadsheets. | Ja | |
mappingdefinition | STRING | Optional: Die Konfiguration des Mappings. Achtung: Wenn Sie eine Mapping-Definition konfigurieren, dann wird dieses Mapping für den Import genutzt, und nicht die Spalten des Quell-Spreadsheets. D.h. wenn Sie im Mapping z.B. Spalten entfernen, dann werden diese auch nicht importiert. | Nein | |
identifierColumn | STRING | Spaltenname im Quell-Spreadsheet, in der der eindeutige identifier des Datensatzes steht. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'identifier' geschaut. | Nein | |
folderColumn | STRING | Spaltenname im Quell-Spreadsheet, in der der Folder des Datensatzes steht. Wenn leer, dann wird der folder 'default' verwendet. | Nein | |
identifier2Column | STRING | Spaltenname im Quell-Spreadsheet, in der ein optionaler (und nicht-eindeutiger) 'identifier2' des Datensatzes steht. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'identifier2' geschaut. | Nein | |
identifier3Column | STRING | Spaltenname im Quell-Spreadsheet, in der ein optionaler (und nicht-eindeutiger) 'identifier3' des Datensatzes steht. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'identifier3' geschaut. | Nein | |
parentIdentifierColumn | STRING | Optional: Spaltenname im Quell-Spreadsheet, in welcher der 'identifier' des Parent-Datensatzes steht. Wird benötigt, wenn man in einen Parent-Variant-Datastore importiert. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'parent_identifier' geschaut. | Nein | |
masterIdentifierColumn | STRING | Optional: Spaltenname im Quell-Spreadsheet, in welcher der 'identifier' des Master-Datensatzes steht. Wird benötigt, wenn man in einen Child-Datastore importiert. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'master_identifier' geschaut. | Nein | |
masterFolderColumn | STRING | Optional: Spaltenname im Quell-Spreadsheet, in welcher der folder des Master-Datensatzes steht. Wenn leer, dann wird der folder 'default' verwendet. Wird benötigt, wenn man in einen Child-Datastore importiert. Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'master_folder' geschaut. | Nein | |
nameColumn | STRING | Optional: Spaltenname im Quell-Spreadsheet, in der der Anzeige-Name des Datensatzes steht. Dies wird nur für Anzeigezwecke im Backend verwendet. Der Wert wird in die 'name'-Spalte des Datastores geschrieben (sofern vorhanden). Wenn leer (Standard) dann wird automatisch im Quell-Spreadsheet oder in der Mapping-Definition nach einer Spalte 'name' geschaut. | Nein | |
mode | STRING | Mit dem Import-Modus kann man steuern, ob man anlegen (Insert), aktualisieren (Update) oder beides (INSERTUPDATE) will. Datenzeilen werden je nach Einstellung übersprungen (SKIPPED) (z.B. bei 'nur anlegen' werden existierende Datensätze im Datastore nicht angefasst und übersprungen.) Standard ist: beides - anlegen und aktualisieren (INSERTUPDATE). | Nein |
|
tagMode | STRING | Der Tag Import Modus legt fest, ob Sie gesetzte Tags beibehalten, neue Tags einfügen, nicht verwendete Tags entfernen oder neue Tags einfügen und nicht verwendete Tags entfernen wollen. | Nein |
|
updateProcessingStatus | STRING | Resettet den processing status der betroffenen Datensätze auf den gesetzten Wert. Standard ist: - Lassen wie es gerade ist oder UNPROCESSED- | Nein |
|
autoExtendSchema | STRING | Aktiviert - Neue Spalten im Quell-Spreadsheet werden automatisch dem Datastore-Schema hinzugefügt. (Bitte mit Bedacht verwenden!). Deaktiviert (Standard) - Das Datastore-Schema bleibt unangetastet, auch wenn das Quell-Spreadsheet neue Spalten beinhaltet. | Nein |
|
untouchedRecordsMode | STRING | Legt fest, ob und wie unangetastete Datensätze berechnet werden. Unberührte Datensätze sind Datensätze, die sich im Datenspeicher befinden, aber nicht in der Eingabetabelle enthalten waren. Ein typischer Anwendungsfall ist z. B. die Ermittlung von Datensätzen, die gestern importiert wurden, aber in der heutigen Importdatei fehlen. | Nein |
|
blockingMode | STRING | Experimentell: Verschiedene Optionen zum Testen, die Einfluss auf die Importgeschwindigkeit von einfachen Importen in einen Datastore haben. (z.B. Import ohne Parent/Variant bzw. Master/Child Beziehungen) | 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 | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
insertResultMessages | STRINGLIST | Eine Liste von Nachrichten mit den Ergebnissen des Imports. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
newAndUpdatedRecords | SPREADSHEET | Ein SPREADSHEET welches neue und aktualisierte (in dieser Reihenfolge) Datensätze enthält. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
Folgende Felder sind im Output enthalten:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
newRecords | SPREADSHEET | Ein SPREADSHEET welches nur neue Datensätze enthält. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
Folgende Felder sind im Output enthalten:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedRecords | SPREADSHEET | Ein SPREADSHEET mit aktualiserten (angefassten) Datensätzen (egal ob inhaltlich geändert oder nicht). | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
Folgende Felder sind im Output enthalten:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
updatedRecordsWithChangedContent | SPREADSHEET | Ein SPREADSHEET mit Datensätzen, bei denen mindestens ein Feld 'inhaltlich' geändert wurde. (Hinweis: Funktioniert nicht in der Step-Vorschau, sondern nur bei einer echten Flow-Ausführung) | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
Folgende Felder sind im Output enthalten:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
untouchedRecords | SPREADSHEET | Ein SPREADSHEET mit 'nicht angefassten' Datensätzen. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
Folgende Felder sind im Output enthalten:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
errors | SPREADSHEET | Ein SPREADSHEET mit Import-Fehlern. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsInsert | NUMBER | Anzahl neu angelegter Datensätze. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsUpdate | NUMBER | Anzahl aktualisierter (im Sinne von 'angefasster') Datensätze (egal ob inhaltlich geändert oder nicht). | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsUpdateWithChangedContent | NUMBER | Anzahl aktualisierter Datensätze, bei denen mindestens ein Feld 'inhaltlich' geändert wurde. (Hinweis: Funktioniert nicht in der Step-Vorschau, sondern nur bei einer echten Flow-Ausführung) | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsInsertUpdate | NUMBER | Gesamtanzahl angelegter und aktualisierter Datensätze. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsUntouched | NUMBER | Anzahl 'nicht-angefasster' Datensätze. Das sind Datensätze, die im Datastore existieren, aber nicht im Quell-Spreadsheet. | Ja | |||||||||||||||||||||||||||||||||||||||||||||||||||
numRecordsSkipped | NUMBER | Anzahl Datensätze, die 'übersprungen' wurden (abhängig vom Import-Modus). z.B. für 'Nur anlegen' werden Datensätze übersprungen, die bereits existieren und aktualisiert werden würden. | Ja |