Wie muss meine CSV für den Massenimport von Vorgängen aufgebaut sein?

Ein CSV-Datensatz für den Import von Vorgängen muss einem gewissen Aufbau folgen. Wie genau, das erfährst du in diesem Artikel.

Der Massenimport per CSV – so gelingt's

Die Kopfzeile – der Ort für alle Verweise auf Felder in deinem Workflow

Die Kopfzeile enthält die Überschriften aller Spalten und gibt damit gleichzeitig auch die Anzahl der Spalten für die Tabelle vor. Jede Zeichenkette wird durch ein Komma abgetrennt. Es gibt keine Mindestzahl und keine Maximalzahl für Spalten.

Allgemeiner Aufbau

Beliebig viele Spalten werden durch Komma voneinander getrennt.

priority, tasks.(...).fields.(...), ...

Beispiel

priority, tasks.Stammdaten.fields.Vorname, tasks.Stammdaten.fields.Nachname

Mit dieser Kopfzeile erstellen wir also drei Spalten.

Die erste Spalte Priority
Die erste Spalte in der Tabelle wird alle Prioritäts-Werte enthalten,
das Spalten-Trennzeichen ,
das Komma trennt diese Spalte von der nächsten Spalte ab (),
die zweite Spalte tasks.(...).fields.(...)
die zweite Spalte bezieht immer ihre Werte aus dem Schritt "Stammdaten" und dort aus dem Feld "Vorname" (tasks.Stammdaten.fields.Vorname),
das Spalten-Trennzeichen ,
erneut ein Komma für eine neue Spalte (,),
die dritte Spalte ...
hier könnten noch beliebig viele weitere Spalten stehen; wir füllen die dritte und damit letzte Beispielspalte mit Werten aus dem Schritt "Stammdaten" und dort aus dem Feld "Nachname" (tasks.Stammdaten.fields.Nachname).
Ergebnis
Die von Vaira erkannte Kopfzeile besteht aus drei Spalten; die erste Spalte ist ein einfacher Prioritätswert, die zweite und dritte Zeile referenziert auf konkrete Feldwerte in Aufgaben.

Die Körperzeile(n) – hier kommen deine einzelnen Vorgänge hin

Körperzeilen sind alle Zeilen unterhalb deiner Kopfzeile – also die Zeilen, die den eigentlich Inhalt mit sich bringen. Sie sind vom Prinzip her genau wie die Kopfzeile aufgebaut.

Jede Zeile in deiner CSV steht für eine Zeile in einer Tabelle bzw. einen einzelnen Vorgang beim Instanzimport. Auch hier dient das Komma der Abtrennung für Spalten.

Eine Besonderheit dabei: du kannst auch leere Zellen erzeugen. Zwei Kommata hintereinander werden dabei als leere Zelle verstanden (,,).

Eine Beispieltabelle inklusive Kopfzeile wie diese hier:

`priority`	`tasks.Stammdaten.fields.Vorname`	`tasks.Stammdaten.fields.Nachname`
High	Thorsten-Dieter	Mustermann
Low		Musterfrau

Wird dann in der CSV zu:

priority,tasks.Stammdaten.fields.Vorname,tasks.Stammdaten.fields.Nachname
High,Thorsten-Dieter,Mustermann
Low,,Musterfrau

In der zweiten Inhaltszeile siehst du hier auch noch einmal gut, wie mit leeren Zellen in CSVs umgegangen wird.

Welche Feldtypen werden beim Import unterstützt und welche Form müssen die Werte haben?

Type	Example	Explanation
Text	`Joachim`	Inhalt für Textfelder
Textbereich	`Markus hat bei der Arbeit einen Hammer zerstört. Muss neu gekauft werden.`	Inhalt für Textbereiche Zeilenumbrüche werden ebenfalls übernommen. Diese nehmen in der CSV auch mehrere Zeilen ein. Dass dadurch keine separaten Vorgänge erzeugt werden liegt daran, dass die Anführungszeichen (`"..."`) um den Text mit Umbruch eindeutig sagen, dass diese Werte zusammen in einer Zelle stehen sollen. Egal, wie viele Absätze gemacht wurden.
Zahl	`142.2345123`	Inhalte für Zahlenfelder Als Kommazeichen dient hier nach internationaler Norm der Punkt. Achte darauf, dass hier keine Kommata genutzt werden. Bei den meisten Programmen kannst du das beim CSV-Export einstellen.
Benutzer	`"user:abcdef,group:123abc,user:aabbbcc"`	Inhalte für Benutzerfelder, um Nutzer oder Gruppen basierend auf ihrer ID hinzufügen Der Teil vor dem `:` ist entweder `user` (Benutzer) oder `group` (Gruppe). Der Teil hinter dem `:` ist dann die ID, die in Vaira für den User oder die Gruppe genutzt wird. Achte darauf, bei mehreren Nutzern und/oder Gruppen die Anführungsstriche oben (`"..."`) zu setzen, damit die Inhalte als zusammenhängendes Feld verstanden werden.
Datum	`YYYY-MM-DD`	Inhalte für Datumsfeldern Das Format des Datums muss `YYYY-MM-DD` sein, also Jahr-Monat-Tag. Beispiel: `2024-04-25`
Timestamp	`YYYY-MM-DDThh:mm:ss+02:00`	Inhalte für Timestamp-Felder Das Format ist RFC3339. Der Wert setzt sich also zusammen aus: `YYYY-MM-DD` für Jahr, Monat und Tag, `T` als Trennzeichen die Uhrzeit im Format `hh:mm:ss`, also Stunden:Minuten:Sekunden, die Zeitverschiebung zwischen GMT und UTC; in Deutschland ist das im Sommer `+02:00` und im Winter `+01:00`. Beispiel: `2024-04-25T13:25:59+02:00` was ausgeschrieben wäre: 25. April 2024 um 13:25 Uhr und 59 Sekunden in der Zeitzone +0200 (Deutsche Sommerzeit).
Auswahl	`"hammer,bohrer,papier"`	Inhalte für Auswahl-Felder Die IDs der einzelnen Objekte, jeweils durch ein `,` getrennt. Auch hier ist wichtig, dass alle Objekte in gemeinsamen Anführungszeichen oben (`"..."`) stehen, damit sie in eine gemeinsame Zelle importiert werden. Wichtig: hier müssen die IDs deiner Auswahlobjekte genutzt werden, nicht die Anzeigenamen!
Checkbox / Boolean	`true`	Inhalte für Checkbox-Felder Diese können entweder `true` (wahr) oder `false` (falsch) sein. Bei einer Checkbox also z.B. "true", wenn die Checkbox abgehakt ist. Andere Werte werden von Vaira nicht akzeptiert.

Sondertypen für weitere Importe

Neben den bekannten Feldtypen

Type	Example	Explanation
`priority`	`lowest`, `low`, `medium`, `high`, `highest`	Du hast fünf Prioritäten für den Import zur Verfügung: von `lowest` (niedrigste) hoch bis zu `highest` (höchste). Die Groß- und Kleinschreibung spielt keine Rolle, du könntest also auch einen Wert wie `LOWEST` oder sogar wie `HiGhEsT` importieren. Außerdem erlaubt Vaira das Prefix `Priority_`. Du kannst also auch Werte wie `PRIORITY_low` oder `priority_HIGHEST` importieren.
`priority_note`	`Neue Deadline wegen paralleler Baumaßnahme.`	Einfacher Text als Notiz für eine Priorisierung.
`annotations.(...)/(...)`	`annoations.meineFirma/label`	Gibt dem Vorgang ein Label. Es können auch mehrere Labels auf einmal erstellt werden; in diesem Fall achte darauf, alle Labels in Anführungszeichen oben zu setzen und als Trennzeichen ebenfalls das Komma zu nutzen: `"annoations.meineFirma/abc-123,annoations.meineFirma/def-456`". Der erste Teil `annotations.` bleibt immer gleich. Der Teil vor dem `/` ist eine Unterkategorisierung. Hier kannst du zum Beispiel deinen Firmennamen nutzen. Du kannst für unterschiedliche Annotationen auch unterschiedliche Unterkategorisierungen nutzen. Eine Besonderheit stellt die Unterkategorisierung `vaira.app` dar, über die du in der nächsten Zeile mehr erfährst. Der Teil hinter dem `/` ist das Label. Hier kannst du Zahlen und Buchstaben verwenden. Den Wert für das Label nimmt sich Vaira dann aus der entsprechenden Zelle in deiner Tabelle.
`annotations.vaira.app/(...)`	`annoations.vaira.app/sync-groups`	Diese Annotation folgt dem bekannten Schema, ist aber für Sync-Groups (also verknüpfte Instanzen) vorbehalten. Wenn du zwei oder mehr Vorgänge erstellst, nutze als Verweis für die Kopfzeile den Befehl links. Anschließend gibst du Vorgängen, die miteinander verknüpft werden sollen, den gleichen Wert in den jeweiligen Zellen mit. Dadurch sind die Vorgänge miteinander verbunden. Was verknüpfte Vorgänge sind und wie du diese in Vaira nutzen kannst, erfährst du in diesem umfassenden Artikel: » Anleitung zum Verknüpfen von Vorgängen in Vaira allgemein

Fehlerhandhabung durch Vaira, Fehlererkennung und Fehlerbehebung

Hier sind einige der häufigsten Fehlerquellen und was du gegen sie tun kannst.

Deine importierte CSV wird von Vaira komplett abgelehnt
In diesem Fall stimmt etwas mit dem Grundaufbau deiner CSV nicht. Bitte überprüfe, ob alle Felder, die du importieren möchtest, auch wirklich so in deinem Vaira-Workflow existieren. Achte dabei auch auf mögliche Buchstabendreher. Überprüfe außerdem, ob alle Feldtypen, die du importieren möchtest, auch von Vaira unterstützt werden.

Der Import funktioniert, aber einige Vorgänge konnten nicht erstellt werden
Sofern der Grundaufbau deiner CSV stimmt und nur einzelne Felder fehlerhafte Werte aufweisen, wird Vaira den Import durchführen und die fehlerhaften Vorgangszeilen überspringen. Im Anschluss an den Import erhältst du eine CSV zum Download, in der alle fehlerhaften Zeilen, die nicht importiert wurden, inklusive Grund für den Fehler ausgegeben werden. Jede Zeile ist dabei eine fehlerhafte Zeile in deiner ursprünglichen CSV. Die neuen Fehlerspalten in der CSV sind:

vaira.row: Verweist auf die Zeile in der originalen Import-CSV, damit du weißt, welche Zeile(n) nicht importiert werden konnten. Die Zählung in deiner originalen CSV beginnt mit 1.
vaira.errors: Ein kurzer Erklärtext dazu, warum diese Zeile nicht importiert werden konnte.

Du kannst die Fehler innerhalb der Fehler-CSV beheben und diese anschließend korrigiert in Vaira hochladen. Dafür musst du die Spalten vaira.row und vaira.errors auch nicht entfernen; Vaira ignoriert diese Spalten beim Import.

Eine Fehlermeldung in der CSV kann zum Beispiel so aussehen:

vaira.row	vaira.error	annotations.vaira.app/comment	tasks.t.fields.boolean
2	invalid value for field tasks.t.fields.boolean: "hello" is not a boolean value	invalid value	hello
16	invalid value for field tasks.t.fields.number: hello is not a number	invalid value	hello