Een bestand aan een record koppelen vanuit een script

Doel

Laat een aanroeper van buiten — een portal, het systeem van een partner — via een aangepaste API een bestand aan een record koppelen, zodat jouw script bepaalt op welk record het terechtkomt en of de aanroeper dat mag.

Waarom dit bestaat

De kolommen Bestand en Afbeelding van een record hebben al hun eigen endpoints, en een formulier gebruikt die. Een portal kan dat niet: een portal praat met het platform via aangepaste API's en via niets anders, omdat de controle die de ene klant weghoudt uit de records van een andere in een script naast portalCustomerId() moet zitten, niet in de aanvraagbouwer van een website.

Daarom kan een script nu een bestand in het veld van een record zetten en er een teruglezen. De bytes reizen als base64-tekst, omdat een script ze op geen andere manier kan vasthouden — de aanroeper codeert, het platform decodeert, en het script geeft alleen de tekenreeks door.

Wat een script kan doen


`putRecordFile(table, id, field, fileName, contentType, contentBase64)`	Slaat het bestand op in het veld van het record. Antwoordt `true`, of `false` als het niet lukte
`getRecordFile(table, id, field)`	Het bestand als object — `fileName`, `contentType`, `sizeBytes`, `contentBase64` — of niets als het veld leeg is

Beide werken als de aanroeper: opslaan vereist Bijwerken op het record en lezen vereist Lezen, precies zoals bij de eigen bestandsendpoints van het record. De maximale grootte van het veld en de regel dat alleen afbeeldingen zijn toegestaan, zijn van het platform, niet van het script.

Stappen

Geef de tabel een kolom van het type Bestand — par_attachment — en, als een lijst de naam moet tonen zonder het bestand op te halen, een kolom van het type Tekst ernaast voor de naam.

Neem het bestand in het aanvraagschema van de aangepaste API op als drie eigenschappen:

"attachmentName": { "type": "string", "maxLength": 260 },
"attachmentType": { "type": "string", "maxLength": 200 },
"attachmentBase64": { "type": "string", "maxLength": 5600000 }

Of, sinds portalronde 10, als één object — dat is wat de bestandskiezer van een getekend scherm verstuurt, en de vorm waarin getRecordFile antwoordt:

"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 }
  }
}

getInput('par_document') geeft het script dan het hele object, en file.fileName leest er een onderdeel van. Is de aanroeper een portalscherm van Parsware, gebruik dan deze vorm — zie Bezoekers een bestand laten bijvoegen.

Maak in het script eerst het record en daarna het bestand — een recordbestand hoort bij een record:

var id = createRecord('par_request', {
  par_name: getInput('subject'),
  par_attachment_name: getInput('attachmentName')
});
if (!isEmpty(getInput('attachmentBase64'))) {
  putRecordFile('par_request', id, 'par_attachment',
    getInput('attachmentName'), getInput('attachmentType'), getInput('attachmentBase64'));
}

Wil je een bestand teruggeven, controleer dan eerst of het record van de aanroeper is, en lees het daarna:

var file = getRecordFile('par_request', id, 'par_attachment');
if (isEmpty(file)) {
  setStatus(404);
} else {
  setOutput('fileName', file.fileName);
  setOutput('contentType', file.contentType);
  setOutput('contentBase64', file.contentBase64);
}

Drie dingen waar mensen over struikelen

Controleer het eigendom voordat je leest. getRecordFile draait als de aanroepende applicatie, en die mag misschien wel elk record in de tabel lezen. De vraag "is dit record van deze aanroeper?" moet je script stellen, en die stel je door het record te lezen en te vergelijken.
De naam op de rij is een momentopname. De bestandsrij bewaart de echte naam; een tekstkolom ernaast laat een lijst "📎 report.pdf" tonen zonder per rij het bestand op te vragen. Schrijf hem weg wanneer je het bestand opslaat, en hij klopt tot iemand het bestand via een andere weg vervangt.
Grote bestanden komen niet via een script. Een bestand boven de limiet van het veld wordt in objectopslag bewaard en door het endpoint van het record gestreamd; getRecordFile weigert het, in plaats van honderden megabytes in een interpreter te laden.

Controleer of het werkte

Open het record in zijn app: de bestandskolom toont het bestand, en als je het downloadt, krijg je terug wat de aanroeper stuurde. De auditgeschiedenis legt de wijziging vast met de naam en de hash van het bestand.

Problemen oplossen

"expects the file's content as base64 text; what was passed does not decode." De aanroeper stuurde de ruwe bytes, of een data-URL waar het voorvoegsel data:…;base64, nog aan vastzit. Stuur alleen de base64.

"The file is N bytes; the limit for this field is M bytes." Boven de limiet, zonder geconfigureerde objectopslag om naar uit te wijken. Vraag de aanroeper om iets kleiners, of configureer een bucket om naar uit te wijken.

"cannot carry a N-byte file; a script reads files up to M bytes." Het bestand is naar objectopslag uitgeweken. Bied het aan via het bestandsendpoint van het record, dat streamt.

Doel​

Waarom dit bestaat​

Wat een script kan doen​

Stappen​

Drie dingen waar mensen over struikelen​

Controleer of het werkte​

Problemen oplossen​