File Upload

Function: a!fileUploadField()

Allows users to upload a file. File upload is only enabled on start and task forms.

See Also: Document, Document or Folder, Interface Recipe: Add Multiple File Upload Components Dynamically

Parameters

Notes

• When a file is uploaded, the component updates with a temporary Document representing the uploaded file. Between the upload and the form submission, the file on the server is an inactive temporary file and not accessible except through fv! variables described in the File Name, File Description, and Validations parameters. This is the only way to access file metadata before the form is submitted.
• When implementing form cancel behavior via a submission, remember that the uploaded files are moved to the target on submission. If this is undesirable in a cancel scenario, it should be deleted (if target is a folder) or reverted via a new version (if the target is a document) by the process after submission.
• If a file is uploaded to a form that is never submitted, the temporary file is automatically deleted after 30 days.
• If any of the following characters appear in a file's name, they are replaced by underscores after submitting the form: \ / " ; : | ? ' < > *
• The user submitting the form must have at least author access to the target folder or document. Any error creating the new document or version causes submission to be canceled and an error to be displayed to the user.
• The file upload component only functions on start and task forms. When placed on a record view or report, the field appears but is automatically disabled.
• Task forms with one or more file upload fields can only be saved if either no file has been uploaded or every uploaded file has been removed.
• The file upload component may not be used to upload new versions of multiple files. To accomplish that, use one component for each file to replace.

Examples

Copy and paste an example into the INTERFACE DEFINITION in EXPRESSION MODE to see it displayed. These examples require an existing target folder or document.

File Upload with no Files

1
2
3
4
5
6
=a!fileUploadField(
  label: "Cover Letter",
  target: cons!APPLICANT_FOLDER,
  value: ri!coverLetter,
  saveInto: ri!coverLetter
)

Displays the following:

Single File Upload with a File

1
2
3
4
5
6
7
=a!fileUploadField(
  label: "Cover Letter",
  target: cons!APPLICANT_FOLDER,
  maxSelections: 1,
  value: ri!coverLetter,
  saveInto: ri!coverLetter
)

Displays the following:

Multiple File Upload with Files

1
2
3
4
5
6
=a!fileUploadField(
  label: "Inspection Photos",
  target: cons!INSPECTION_PHOTOS_FOLDER,
  value: ri!photos,
  saveInto: ri!photos
)

Displays the following:

Add one of these parameter configurations to a file upload component to achieve a the desired behavior. These examples demonstrate how to use the fv! variables available in the File Name, File Description, and Validations parameters to set file metadata or create complex validations.

Swap spaces for underscores in file names

1
fileNames: substitute(fv!file.name, " ", "_")

Set file descriptions to a value plus file index

1
fileDescriptions: "Application ABC-123 attachment " & fv!index

All files must be PDFs

1
2
3
4
5
6
7
8
9
validations: with(
  local!invalidExtensions: difference(upper(fv!files.extension), "PDF"),
  if(
    length(local!invalidExtensions) > 0, 
    "Attachments must be pdf files. Remove: " & 
      index(fv!files, "name", wherecontains(local!invalidExtensions, upper(fv!files.extension)), {}), 
    ""
  )
)

No files may be PDFs

1
2
3
4
5
6
validations: if(
  contains(upper(fv!files.extension), "PDF"), 
  "Attachments must not be pdf files. Remove: " & 
    index(fv!files, "name", wherecontains("PDF", upper(fv!files.extension))), 
  ""
)

Files may only be PNG or JPG

1
2
3
4
5
6
7
8
9
validations: with(
  local!invalidExtensions: difference(upper(fv!files.extension), { "PNG", "JPG" }),
  if(
    length(local!invalidExtensions) > 0, 
    "Attachments must be images. Remove: " & 
      index(fv!files, "name", wherecontains(local!invalidExtensions, upper(fv!files.extension)), {}), 
    ""
  )
)

Files must be larger than 5MB

1
2
3
4
5
6
validations: if(
  or(fv!files.size < 5000000), 
  "Attachments must be at least 5MB. Remove: " & 
    index(fv!files, "name", where(fv!files.size < 5000000), {}), 
  ""
)

Files must be smaller than 5MB

1
2
3
4
5
6
validations: if(
  or(fv!files.size > 5000000), 
  "Attachments may not exceed 5MB. Remove: " & 
    index(fv!files, "name", where(fv!files.size > 5000000), {}), 
  ""
)

Up to 5 files are allowed

1
validations: if(length(fv!files) > 5, "Only 5 attachments are allowed", "")

Exactly 5 files are required

1
validations: if(not(length(fv!files) = 5), "5 files must be attached", "")

At least 5 files are required

1
validations: if(length(fv!files) < 5, "There must be at least 5 attachments", "")

Old Versions

There are older versions of this Interface Component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.