File Upload Component
This function cannot be used with Custom Record Field Expressions.
For a full list of functions and their feature compatibility, explore the Appian Functions table.

Function

a!fileUploadField( label, labelPosition, instructions, helpTooltip, target, fileNames, fileDescriptions, maxSelections, value, saveInto, required, requiredMessage, disabled, validations, validationGroup, buttonStyle, buttonSize, accessibilityText, showWhen, uploadMethods, buttonDisplay, placeholder, showVirusScanMessage )

Allows users to upload a file. File upload is only enabled on start and task forms. Permitted file extensions can be controlled via the File Upload settings in the Admin Console.

See Also: Document, Document or Folder

Parameters

Name Keyword Types Description

Label

label

Text

Text to display as the field label.

Label Position

labelPosition

Text

Determines where the label appears. Valid values:

  • "ABOVE" (default) Displays the label above the component.
  • "ADJACENT" Displays the label to the left of the component.
  • "COLLAPSED" Hides the label. The label will still be read by screen readers; see accessibility considerations for more information.
  • "JUSTIFIED" Aligns the label alongside the component starting at the edge of the page.

Instructions

instructions

Text

Supplemental text about this field.

Help Tooltip

helpTooltip

Text

Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".

Target Folder

target

Document or Folder

Determines the eventual location of the uploaded files.

File Names

fileNames

Text

Determines the names for the files. When not provided, the uploaded filenames are used. Access name, size, and extension of each file using the variables fv!file.name, fv!file.size, and fv!file.extension. Access the index of each file using the variable fv!index.

File Descriptions

fileDescriptions

Text

Determines the descriptions for the files. When not provided, the descriptions of the new files are empty. Access name, size, and extension of each file using the variables fv!file.name, fv!file.size, and fv!file.extension. Access the index of each file using the variable fv!index.

Maximum Selections

maxSelections

Number (Integer)

Maximum number of allowed files. Once this number is reached, further uploads are blocked until a file is removed.

Display Value

value

List of Document

The files associated with this field.

Save Input To

saveInto

List of Save

One or more variables that are updated with the files when the user uploads files. Removing all uploaded files saves a null document. Use a!save() to save a modified or alternative value to a variable.

Required

required

Boolean

Determines if a value is required to submit the form. Default: false.

Required Message

requiredMessage

Text

Custom message to display when the field's value is required and not provided.

Disabled

disabled

Boolean

Determines if the field should display as potentially editable but grayed out. When files are present in this state, they may not be deleted. Default: false.

Validations

validations

List of Text String

Validation errors to display below the field when the value is not null. Access the names, sizes, and extensions of the uploaded files using the variables fv!files.name, fv!files.size, and fv!files.extension.

Validation Group

validationGroup

Text

When present, this field is only validated when a button in the same validation group is pressed. See the documentation for more information about how to use validation groups.

Button Style

buttonStyle

Text

Determines the style of the upload button. Valid values:

  • "NORMAL" Displays the label and border in the accent color.
  • "PRIMARY" Displays the label in white on an accent color background.
  • "SECONDARY" (default) Displays the label and border in gray.
  • "LINK" Displays the label in the accent color and has no border until focused.

Button Size

buttonSize

Text

Determines the size of the upload button. Valid values: "SMALL" (default), "STANDARD", "LARGE".

Accessibility Text

accessibilityText

Text

Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Visibility

showWhen

Boolean

Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.

Upload Methods (Mobile only)

uploadMethods

List of Text

(Mobile only) Determines which mobile upload methods are displayed to users. If one method is specified, the upload button will be customized. Multiple may be applied. If value is null, all methods are provided. Valid values include: null (Default),“SIGNATURE”, “CAMERA”, “CHOOSE_PHOTO”, “CHOOSE_FILE”.

Button Display

buttonDisplay

Text

Determines if the file upload will display a button with a label or an icon. Valid values: "LABEL", "ICON", and "LABEL_AND_ICON". Default behavior displays "LABEL" on web and "LABEL_AND_ICON" on mobile.

Placeholder

placeholder

Text

Text to display when no file is uploaded. Default: "Drop files here".

Show scanning for viruses message

showVirusScanMessage

Boolean

Determines whether the "Scanning for viruses" message appears during file upload. When set to false, the message is hidden, but the file is still scanned for viruses. An error message will still appear if real-time virus scanning is enabled and the uploaded file contains a virus. Default: true.

Usage considerations

Temporary files

  • 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.
  • If a file is uploaded to a form that is never submitted, the temporary file is automatically deleted after 30 days.

Forms and tasks containing file upload components

  • 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.
  • 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.
  • 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.

Permissions and virus scanning

  • 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.
  • If real-time virus scanning is enabled for file uploads in the Administration Console, the uploaded file will always be scanned for viruses, regardless of whether the virus scanning message is shown.

Uploading files

  • The uploadMethods parameter is only supported within the Appian Mobile application. This parameter allows you to limit the upload methods a mobile user has access to when tapping an upload button. This can be helpful in, for example, ensuring users do not upload photos of a signature instead of drawing their signature within the application.
  • 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.
  • If any of the following characters appear in a file's name, they are replaced by underscores after submitting the form: \ / " ; : | ? ' < > *.

Examples

Copy and paste an example into the INTERFACE DEFINITION in EXPRESSION MODE to see it displayed.

The following examples require an existing target folder or document.

File upload with no files

1
2
3
4
5
6
a!fileUploadField(
  label: "Upload Resume",
  target: cons!APPLICANT_FOLDER,
  value: ri!resume,
  saveInto: ri!resume
)

Displays the following:

screenshot of a file upload with no file

File upload with the icon style and no files

Use the interactive editor below to test out your code:

To test out different file upload styles and placeholder texts, change the value of the buttonDisplay parameter to "LABEL_AND_ICON" and enter a different text value for the placeholder parameter.

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:

screenshot of a single file upload with a single file

File upload with multiple 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:

screenshot of a file upload with multiple files

### Signature-capture only field on the Appian Mobile application***

1
2
3
4
5
6
7
8
a!fileUploadField(
  label: "Signature",
  target: cons!APPLICANT_FOLDER,
  maxSelections: 1,
  value: ri!signature,
  saveInto: ri!signature,
  uploadMethods: "SIGNATURE"
)

Resulting behavior: Users in the Appian Mobile application, when tapping on the "Signature" file upload button, are instantly prompted to draw their signature and cannot use other upload methods such as taking a photo.

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: a!localVariables(
  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: a!localVariables(
  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 five files are allowed

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

Exactly five files are required

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

At least five 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.

Old Versions Reason for Update
a!fileUploadField_17r1

Multiple file upload is now supported directly within the component. This removes the need to generate many individual file upload fields.

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

Open in Github Built: Tue, May 17, 2022 (03:02:27 PM)

On This Page

FEEDBACK