Mit dieser Schnittstelle laden Sie eine CSV-Datei per REST in einen Datapool. Der Inhalt einer bestehenden CSV-Quelle wird dabei vollständig durch den Inhalt der Datei ersetzt. Daten werden nicht ergänzt oder einzeln aktualisiert.

Voraussetzungen

• Ein Datapool mit einer CSV-Quelle. Die Quelle muss in der Datapool-Definition angelegt und einmal manuell befüllt worden sein. Dabei wird die Zeichenkodierung der Quelle festgelegt und die Datei bei der Quelle abgelegt. Beides verwendet die Schnittstelle danach weiter.
• Die GUID des Datapools (Feld «GUID» oben in der Datapool-Definition) und die GUID der CSV-Quelle.
• Eine Client ID und ein Client Secret, erstellt in der Benutzerverwaltung (siehe Autorisierung). Der zugehörige Benutzer benötigt die Rolle FORM_ADMIN im Mandanten des Datapools.
• Eine CSV-Datei mit Semikolon ; als Trennzeichen. Die erste Zeile enthält die Spaltennamen, jeder Spaltenname muss ausgefüllt sein. Das Format entspricht dem manuellen Upload.

Ablauf

1. Access Token beziehen

Der Zugriff ist über OAuth2 geschützt. Fordern Sie zuerst ein Access Token an. Es ist 60 Minuten gültig; danach muss ein neues angefordert werden.

curl -X POST "{SERVICE-URL}/formservice/services/rest/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"{CLIENT-ID}","client_secret":"{CLIENT-SECRET}"}'

Aus der Antwort benötigen Sie den Wert von access_token.

2. CSV-Datei hochladen

Senden Sie die Datei als Body eines POST-Requests. Die beiden GUIDs stehen im Pfad, das Token im Header Authorization. Verwenden Sie --data-binary, damit die Datei unverändert (Bytes und Zeilenumbrüche) übertragen wird.

curl -X POST "{SERVICE-URL}/formservice/services/rest/datapool/{DATAPOOL-GUID}/source/{SOURCE-GUID}/import/csv" \
  -H "Authorization: Bearer {ACCESS-TOKEN}" \
  -H "Content-Type: text/csv" \
  --data-binary "@daten.csv"

Beispiel für den Inhalt von daten.csv:

Beruf;Ort;Anzahl
Beruf A;Ort A;3
Beruf B;Ort B;1

3. Antwort prüfen

Bei Erfolg antwortet der Server mit dem Status 200 und der Anzahl importierter Datenzeilen (ohne Kopfzeile):

{
  "message": "File was uploaded successfully.",
  "rows": 2
}

Die neuen Daten sind danach verfügbar. Ob der Datapool die erwarteten Daten liefert, prüfen Sie mit der Anzeige in der Datapool-Definition (Tab «Anzeigen»).

Was beim Import geschieht

1. Die bisherigen Daten der Quelle werden gelöscht und durch die Daten der Datei ersetzt. Beides geschieht in einem Schritt: Tritt ein Fehler auf, bleiben die bisherigen Daten unverändert.
2. Ist bei der Quelle bereits eine Datei abgelegt (vom manuellen Upload), wird deren Inhalt durch die hochgeladene Datei ersetzt. Der Dateiname bleibt unverändert, Änderungsdatum und Änderungsbenutzer der abgelegten Datei werden aktualisiert. Eine Datei wird nicht neu angelegt. Die im Admin herunterladbare Datei entspricht damit den aktuellen Daten.
3. Der Zwischenspeicher des Datapools wird geleert, damit Formulare und Abfragen die neuen Daten verwenden.

Eine Datei ohne Datenzeilen wird abgelehnt, damit ein leerer Upload die Quelle nicht leert.

Wenn es nicht funktioniert

Verwendung in Swagger UI

Die REST-Dokumentation (Swagger UI) erreichen Sie unter {SERVICE-URL}/formservice/doc/rest-api/. Die Schnittstelle erscheint dort unter dem Eintrag datapool.

1. Token beziehen (Schritt 1) und über «Authorize» hinterlegen, siehe Autorisierung.
2. POST /datapool/{dataPoolId}/source/{sourceId}/import/csv aufklappen und «Try it out» wählen.
3. Die beiden GUIDs eintragen und den Inhalt der CSV-Datei als Request-Body einfügen.
4. «Execute» klicken und die Antwort prüfen.