Besucher eine Datei anhängen lassen

Ziel

Jemand in Ihrem Portal soll dem Datensatz, den er gerade erstellt, ein Dokument anhängen können – eine Quittung, ein Foto, ein unterschriebenes Formular.

Bevor Sie beginnen

• Ein Portal, bei dem Wer es öffnen kann auf Angemeldete Personen eingestellt ist, denn das Anhängen einer Datei ist Teil eines Schreibvorgangs, und ein Schreibvorgang braucht jemanden, dem er zugeordnet werden kann. Siehe Besucher zur Anmeldung auffordern.
• Eine Tabelle mit einer Spalte vom Typ Datei oder Bild.
• Die Zeile Datensatz anlegen steht bereits in der Freigabeliste des Portals, aus Besucher Änderungen speichern lassen. Für die Datei müssen Sie nichts hinzufügen – sie reist im Body des Schreibvorgangs mit.

Schritte

1. Zeichnen Sie eine Dateiauswahl auf Ihren Bildschirm und binden Sie ihren Wert an ein Zustandsfeld des Bildschirms – state.document.

2. Senden Sie sie mit dem Datensatz. Die Auswahl übergibt Ihrem Bildschirm die Datei, nicht ihren Namen, also kommt sie in dasselbe Objekt wie alles andere:

   createRecord("par_claim", {
     par_name: getState("subject"),
     par_document: getState("document")
   }, "saved");

3. Beschreiben Sie sie im Anfrageschema der API, als Objekt mit vier Eigenschaften:

   "par_document": {
     "type": "object",
     "additionalProperties": false,
     "required": ["fileName", "contentType", "contentBase64"],
     "properties": {
       "fileName":      { "type": "string", "maxLength": 260 },
       "contentType":   { "type": "string", "maxLength": 200 },
       "sizeBytes":     { "type": "integer" },
       "contentBase64": { "type": "string", "maxLength": 5600000 }
     }
   }

4. Speichern Sie zuerst den Datensatz, dann die Datei, denn eine Datei gehört zu einem Datensatz, und solange die Zeile nicht existiert, gibt es nichts, woran man sie anhängen könnte:

   var file = getInput('par_document');
   
   var id = createRecord('par_claim', {
     par_name: getInput('par_name'),
     par_raised_by_email: portalEmail(),
     par_document_name: isEmpty(file) ? '' : file.fileName
   });
   
   if (!isEmpty(file)) {
     putRecordFile('par_claim', id, 'par_document',
       file.fileName, file.contentType, file.contentBase64);
   }

5. Leeren Sie sie nach einem erfolgreichen Senden, damit sich die Auswahl zusammen mit dem Rest des Formulars leert:

   setState("document", null);

Was eine ausgewählte Datei eigentlich ist

Vier Felder, und es sind dieselben vier, die ein Skript von getRecordFile zurückbekommt – eine hinausgehende und eine zurückkommende Datei haben also eine einzige Form:

fileName	wie sie auf dem eigenen Rechner des Besuchers heißt
contentType	ihr Medientyp, wie ihn sein Browser gemeldet hat
sizeBytes	wie groß sie ist – das, was eine Beschriftung angibt
contentBase64	die Bytes, als Text

Eine Beschriftung, die an das Ganze gebunden ist, zeigt den Namen der Datei, sodass text(state.document) contract.pdf ergibt statt etwas Unlesbares. Um ein ausgewähltes Bild anzuzeigen, binden Sie die Quelle eines img an fileUrl(state.document).

Warum es in der Freigabeliste keine Zeile „Datei anhängen“ gibt

Die Freigabeliste eines Portals nennt Operationen auf Tabellen – eine Liste lesen, einen Datensatz lesen, anlegen, ändern, löschen –, und eine Datei ist keine davon. Sie reist im Body des Schreibvorgangs mit: Ein Portal, das einen Antrag anlegen darf, darf also an den Antrag, den es gerade anlegt, ein Dokument hängen, und ein Portal, das das nicht darf, kann es nicht. Es gibt nichts zusätzlich zu gewähren und nichts zusätzlich, dessen Entzug man vergessen könnte.

Deshalb liegt auch kein Datei-Endpunkt im öffentlichen Internet. Die Bytes gehen an Ihre benutzerdefinierte API, Ihr Skript entscheidet, bei welchem Datensatz sie landen, und putRecordFile speichert sie mit den eigenen Berechtigungen des Datensatzes – es braucht „Aktualisieren“ für diese Zeile, genau wie ein Formular innerhalb der Plattform.

An einen Datensatz anhängen, den es schon gibt

Genauso, über eine Änderung. Senden Sie die Datei in den Werten von updateRecord, und lassen Sie die Custom API hinter der Zeile Datensatz ändern den Datensatz lesen, ihn ändern und dann putRecordFile aufrufen. Bei einer Tabelle mit einer Regel, wessen Datensätze ein Besucher sieht, folgt auch die Datei dieser Regel: Ein Besucher kann eine Datei nur an einen Datensatz hängen, den die Regel ihm gibt.

Wie groß eine Datei sein darf

4 MB, und die Auswahl sagt das, bevor irgendetwas hochgeladen wird.

Das ist weniger, als die Plattform speichern kann – eine Bereitstellung mit konfiguriertem Objektspeicher nimmt über den eigenen Datei-Endpunkt eines Datensatzes weit größere Dateien an –, und der Unterschied ist Absicht. Hier wird die Datei als Text in einem JSON-Body kodiert und im Browser des Besuchers gehalten, während er das Formular zu Ende ausfüllt. Ein sehr großer Anhang auf diesem Weg ist eine sehr große Zeichenkette im Browser eines Fremden und ein Body, den man keinem Vertrag zum Parsen zumuten sollte.

Derselbe Bildschirm innerhalb der Plattform

Nichts ändert sich. Öffnen Sie dieselbe App in Parsware, und derselbe Handler schreibt direkt in die Tabelle, wobei die Datei über den eigenen Endpunkt der Plattform in die Spalte Datei des Datensatzes geht. Sie zeichnen einen Bildschirm, nicht zwei.

Drei Dinge, über die man leicht stolpert

• Schreiben Sie den Datensatz vor der Datei. putRecordFile braucht eine Datensatz-ID. Ein Skript, das zuerst anhängen will, hat nichts, woran es anhängen könnte.
• Halten Sie den Namen der Datei in einer Textspalte daneben fest. Eine Liste, die „📎 invoice.pdf“ anzeigen soll, sollte eine einfache Textspalte lesen, statt jede Datei abzurufen, um ihren Namen herauszufinden.
• Eine Ablehnung lesen Fremde. Wenn Sie einen Anhang ablehnen – etwa die falsche Dateiart –, schreiben Sie den Satz für die Öffentlichkeit: Er erscheint neben der Schaltfläche, die gedrückt wurde.

Prüfen, ob es funktioniert hat

Hängen Sie im Portal eine Datei an, drücken Sie die Schaltfläche, und öffnen Sie dann den Datensatz in der Plattform. Das Dokument liegt in seinem Feld Datei, mit dem Namen, den Sie daneben gespeichert haben – und das Portal hat nie einen Datensatz-Endpunkt gesehen.