Permitir que los visitantes adjunten un archivo

Objetivo

Permitir que alguien en su portal adjunte un documento (un recibo, una fotografía, un formulario firmado) al registro que está creando.

Antes de empezar

• Un portal en el que Quién puede abrirlo está establecido en Personas que inician sesión, porque adjuntar un archivo forma parte de una escritura, y una escritura necesita a alguien a quien atribuírsela. Consulte Pedir a los visitantes que inicien sesión.
• Una tabla con una columna Archivo o Imagen.
• La fila Crear ya presente en la lista de permitidos del portal, de Permitir que los visitantes guarden cambios. No hay que agregar nada para el archivo: viaja en el cuerpo de la escritura.

Pasos

1. Dibuje un selector de archivos en su pantalla y enlace su valor a un campo de estado de la pantalla: state.document.

2. Envíelo con el registro. El selector entrega a su pantalla el archivo, no su nombre, así que va en el mismo objeto que todo lo demás:

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

3. Descríbalo en el esquema de solicitud de la API, como un objeto con cuatro propiedades:

   "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. Guarde primero el registro y después el archivo, porque un archivo pertenece a un registro y no hay nada a lo que adjuntarlo hasta que la fila existe:

   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. Vacíelo después de un envío correcto, para que el selector se vacíe junto con el resto del formulario:

   setState("document", null);

Qué es realmente un archivo elegido

Cuatro campos, y son los mismos cuatro que recibe un script de getRecordFile; así, un archivo que sale y un archivo que vuelve tienen una única forma:

fileName	cómo se llama en el propio equipo del visitante
contentType	su tipo de medio, tal como lo indicó su navegador
sizeBytes	su tamaño: lo que muestra un rótulo
contentBase64	los bytes, como texto

Un rótulo enlazado al objeto entero se lee como el nombre del archivo, así que text(state.document) dice contract.pdf en lugar de algo ilegible. Para mostrar una imagen elegida, enlace el origen de un img a fileUrl(state.document).

Por qué no hay una fila «adjuntar un archivo» en la lista de permitidos

La lista de permitidos de un portal enumera operaciones sobre tablas (leer una lista, leer uno, crear, cambiar, eliminar), y un archivo no es ninguna de ellas. Viaja en el cuerpo de la escritura, así que un portal que puede crear una reclamación puede poner un documento en la reclamación que está creando, y un portal que no puede, no puede. No hay nada más que conceder, ni nada más que olvidarse de retirar.

Por eso tampoco hay ningún punto de conexión de archivos expuesto a internet. Los bytes van a su API personalizada, su script decide en qué registro acaban y putRecordFile los guarda con los propios permisos del registro: necesita permiso de actualización sobre esa fila, exactamente igual que un formulario dentro de la plataforma.

Adjuntar a un registro que ya existe

Igual, mediante un cambio. Envíe el archivo en los valores de updateRecord, y haga que la API personalizada de la fila Cambiar un registro lea el registro, lo actualice y después llame a putRecordFile. En una tabla con una regla sobre qué registros ve un visitante, el archivo también la cumple: un visitante solo puede adjuntar un archivo a un registro que la regla le da.

Qué tamaño puede tener un archivo

4 MB, y el selector lo indica antes de que se cargue nada.

Es menos de lo que la plataforma es capaz de guardar (una implementación con almacenamiento de objetos configurado admite archivos mucho mayores a través del propio punto de conexión de archivos del registro), y la diferencia es deliberada. Aquí el archivo se codifica como texto dentro de un cuerpo JSON y se conserva en el navegador del visitante mientras termina de rellenar el formulario. Un adjunto muy grande por ese camino es una cadena muy grande en el navegador de un desconocido y un cuerpo que no se debería pedir a ningún contrato que analice.

La misma pantalla dentro de la plataforma

No cambia nada. Abra la misma aplicación en Parsware y el mismo controlador escribe directamente en la tabla, y el archivo va a la columna Archivo del registro a través del propio punto de conexión de la plataforma. Dibuja una pantalla, no dos.

Tres cosas que suelen pillar desprevenido

• Escriba el registro antes que el archivo. putRecordFile necesita un id de registro. Un script que intenta adjuntar primero no tiene nada a lo que adjuntar.
• Guarde el nombre del archivo en una columna de texto junto a él. Una lista que quiere mostrar «📎 invoice.pdf» debería leer una columna de texto normal, no descargar cada archivo para averiguar su nombre.
• Un rechazo lo leen desconocidos. Si rechaza un adjunto (por ser del tipo equivocado, por ejemplo), escriba la frase pensando en el público: aparece junto al botón que se pulsó.

Comprobar que ha funcionado

Adjunte un archivo en el portal, pulse el botón y después abra el registro en la plataforma. El documento está en su campo Archivo, con el nombre que guardó al lado, y el portal nunca vio un punto de conexión de registros.