How does the File Upload work?

PIPEFORCE Forms also supports file uploads and file previews.

To make a widget in a form an upload widget, you need to follow these steps:

Step 1: Add a content reference object to your Form Schema

The widget which should become the upload widget must be declared of type object in the Form Schema. The objectmust, in turn, contain the properties for the content reference declaration. See the example below where the widget with id myFile will be declared by a content reference object.

You can copy & paste this content reference declaration into your Form Schema:

...

    "myFile": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "contentLength": {"type": "number"},
        "contentType": {"type": "string"},
        "contentEncoding": {"type": "string"},
        "content": {"type": "string"}
      }
    }
  
...

Or even better, you can refer to the public schema for content-reference which is located here https://resource.pipeforce.io/latest/schema/json/content-reference.json
and include it into your Form Schema on each widget which must become an upload widget, like this example shows:

...

    "myFile": {
      "$ref": "https://resource.pipeforce.io/latest/schema/json/content-reference.json"
    }
  
...

For more details see:

Step 2: Configure the render type in your Form Config

As a second step you have to define, how the upload widget should look like.

To do so, add "render": "filepicker" or "render": "pdfviewer" to your Form Config.

For example:

{
	"title": "...",
	"description": "...",
	"schema": "...",
	"output": "...",
	"layout": {
		"items": [
			{
				"field": "myFile",
				"render": "filepicker"
			}
		]
	}
}

This will render a file picker widget like this:

Step 3: Handle the uploaded file

Finally, you have to create a handler pipeline which processes the uploaded file.

After submit, the uploaded file is stored in content reference format inside the form output data JSON. The handler pipeline (controller) can parse this and further process the files if required.

Here is an example of a form output data JSON which contains a content reference which points to the uploaded file:

Note that contentEncoding is set to outbound-url and therefore the attribute content contains a url pointing to the PDF file data to be extra loaded by the forms framework on form load. In this example this is the path to a property in the property store which contains the file as attachment. The name of the attachment is by default the same name as set by the name attribute of the content reference. In this example this is invoice-123.pdf.

For more details, see:

Forms Framework | The Pipeline (Controller)

Implementation Details

In order to better understand the file upload in general in PIPEFORCE, here are some implementation details in case you are interested:

In case a form schema contains a content reference section, a file chooser is rendered in the form.
See .
The user can click this file chooser and select the local file to be uploaded.
After the user has selected the file, the browser creates a temp property in the property store at location global/tmp/{randomUuid}.
The browser then immediately starts the file upload and adds it as attachment to this tmp property. If there are more than one file to be uploaded, all files will be added to this property as attachment. The name of the attachment will be set to the original name of the file.
See .
All content reference fields will be updated by the browser as followed:
1. The name field will be set to the original file name.
2. The contentLength will be set to the size of the file.
3. The contentType will be set to the type of the file (if possible).
4. The contentEncoding will be set to outbound-url.
5. The content field will be set to the PIPEFORCE URI pointing to the tmp property. For example:
  $uri:property:global/tmp/adfe1656-2bb7-11ee-be56-0242ac120002
If finally the user submits the form, all form data including the updated content reference part will be stored in the property store at the output path as configured by the output attribute in the Form Config.
The property.created event is fired and the listening pipeline is called. This pipeline can then further process the form data and move the uploaded files to their final destination if required by moving the tmp property + updating the PIPEFORCE URI in the form data with the final location.
See .