DatastoreWriter - Basis

← Basis Add-On Übersicht

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	Anlegen & aktualisieren Nur anlegen Nur aktualisieren
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	- Lassen wie es gerade ist - Anhängen Ersetzen Ersetzen wenn nicht leer
updateProcessingStatus	STRING	Resettet den processing status der betroffenen Datensätze auf den gesetzten Wert. Standard ist: - Lassen wie es gerade ist oder UNPROCESSED-	Nein	- Lassen wie es gerade ist oder UNPROCESSED - UNPROCESSED INPROCESS PROCESSED_SUCCESS PROCESSED_ERROR PROCESSED_MARK_DELETE
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	Deaktiviert Aktiviert - Automatische Schema-Erweiterung
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	Deaktiviert (Standard) Alle Folder Nur 'betroffene' Folder
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	Standard (blockierend, Langsamer) Schneller (Nicht-blockierend)

Outputs

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

Name	Datentyp	Beschreibung	Werte
insertResultMessages	STRINGLIST	Eine Liste von Nachrichten mit den Ergebnissen des Imports.
newAndUpdatedRecords	SPREADSHEET	Ein SPREADSHEET welches neue und aktualisierte (in dieser Reihenfolge) Datensätze enthält.
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Standardwert datastorename SINGLE folder SINGLE identifier SINGLE identifier2 SINGLE identifier3 SINGLE datastoretags MULTIPLEVALUE parent_identifier SINGLE master_folder SINGLE master_identifier SINGLE
newRecords	SPREADSHEET	Ein SPREADSHEET welches nur neue Datensätze enthält.
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Standardwert datastorename SINGLE folder SINGLE identifier SINGLE identifier2 SINGLE identifier3 SINGLE datastoretags MULTIPLEVALUE parent_identifier SINGLE master_folder SINGLE master_identifier SINGLE
updatedRecords	SPREADSHEET	Ein SPREADSHEET mit aktualiserten (angefassten) Datensätzen (egal ob inhaltlich geändert oder nicht).
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Standardwert datastorename SINGLE folder SINGLE identifier SINGLE identifier2 SINGLE identifier3 SINGLE datastoretags MULTIPLEVALUE parent_identifier SINGLE master_folder SINGLE master_identifier SINGLE
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)
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Standardwert datastorename SINGLE folder SINGLE identifier SINGLE identifier2 SINGLE identifier3 SINGLE datastoretags MULTIPLEVALUE parent_identifier SINGLE master_folder SINGLE master_identifier SINGLE
untouchedRecords	SPREADSHEET	Ein SPREADSHEET mit 'nicht angefassten' Datensätzen.
	Folgende Felder sind im Output enthalten: Feld Datentyp Beschreibung Standardwert datastorename SINGLE folder SINGLE identifier SINGLE identifier2 SINGLE identifier3 SINGLE datastoretags MULTIPLEVALUE parent_identifier SINGLE master_folder SINGLE master_identifier SINGLE
errors	SPREADSHEET	Ein SPREADSHEET mit Import-Fehlern.
numRecordsInsert	NUMBER	Anzahl neu angelegter Datensätze.
numRecordsUpdate	NUMBER	Anzahl aktualisierter (im Sinne von 'angefasster') Datensätze (egal ob inhaltlich geändert oder nicht).
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)
numRecordsInsertUpdate	NUMBER	Gesamtanzahl angelegter und aktualisierter Datensätze.
numRecordsUntouched	NUMBER	Anzahl 'nicht-angefasster' Datensätze. Das sind Datensätze, die im Datastore existieren, aber nicht im Quell-Spreadsheet.
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.