FunctionCopy link to clipboard
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 one or more files. To upload files outside of a start form or task, use a!submitUploadedFiles() in the saveInto parameter of a submit button or link. Uploaded documents are not accessible until after form submission.
Permitted file extensions can be controlled via the File Upload settings in the Admin Console.
See Also:
ParametersCopy link to clipboard
Name | Keyword | Types | Description |
---|---|---|---|
Label |
|
Text |
Text to display as the field label. |
Label Position |
|
Text |
Determines where the label appears. Valid values:
|
Instructions |
|
Text |
Supplemental text about this field. |
Help Tooltip |
|
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 |
Target Folder |
|
Document or Folder |
Determines the eventual location of the uploaded files. |
File Names |
|
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 |
|
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 |
|
Number (Integer) |
Maximum number of allowed files. Once this number is reached, further uploads are blocked until a file is removed. |
Display Value |
|
List of Document |
The files associated with this field. |
Save Input To |
|
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 |
|
Boolean |
Determines if a value is required to submit the form. Default: false. |
Required Message |
|
Text |
Custom message to display when the field's value is required and not provided. |
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 |
|
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 |
|
Text |
When present, the requiredness of the field is only evaluated when a button in the same validation group is pressed. The value for this parameter cannot contain spaces. For example, |
Button Style |
|
Text |
Determines the style of the upload button. Valid values:
|
Button Size |
|
Text |
Determines the size of the upload button. Valid values: |
Accessibility Text |
|
Text |
Additional text to be announced by screen readers. Used only for accessibility; produces no visible change. |
Visibility |
|
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) |
|
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), |
Button Display |
|
Text |
Determines if the file upload will display a button with a label or an icon. Valid values: |
Placeholder |
|
Text |
Text to display when no file is uploaded. Default: |
Show scanning for viruses message |
|
Boolean |
Determines whether the |
Usage considerationsCopy link to clipboard
Submitting filesCopy link to clipboard
When files are uploaded in the file upload component, they are saved to a temporary folder. They are not saved to the target until they are submitted.
In start forms and tasks, on the button used to submit the form, make sure that the submit parameter set to true
. When this button is clicked, the uploaded files will be saved to the target.
Outside of start forms and tasks, use a!submitUploadedFiles()
in the saveInto parameter of a button or link. This button or link could be used to submit the files, as in this a!submitUploadedFiles() example, or the entire form, as in this example. When this button is clicked, the uploaded files will be saved to the target folder.
Give end users Editor permissions to the targetCopy link to clipboard
In order to submit an uploaded file, users must have at least Editor permissions to the target folder or document.
For portals, give the portal service account Editor permissions to the target folder or document.
Any error saving the new document or version causes submission to be canceled and an error to be displayed to the user.
Avoid saving unnecessary filesCopy link to clipboard
In a start form or taskCopy link to clipboard
For a start form or task, both the cancel and submit buttons will usually have the submit parameter set to true
. As soon as one of these buttons are clicked, any uploaded files will be saved to their target.
To avoid saving files from a canceled form, configure the cancel flow in the process model to handle the unnecessary files. If the target is a folder, delete any uploaded files. If the target is a document, revert the file upload via a new version of the document.
Outside of a start form or taskCopy link to clipboard
If you are using the file upload component outside of a start form or task, use a!submitUploadedFiles()
in the saveInto parameter of a button or link. Do not use it in the file upload component's saveinto parameter. This ensures that the file is only saved to the target when the user is ready to submit it.
See a!submitUploadedFiles() for more information.
For portals, test the file upload in a published portalCopy link to clipboard
To make sure files will be uploaded correctly in a portal, publish the portal and test the file upload on the portal website. The file may seem to submit correctly when you test it in the interface object, but it may not work in the portal itself. For example, if the portal service account doesn't have Editor permissions to the target folder, you will see an error in the portal, but not in the interface object.
See a!submitUploadedFiles() for more information on testing and troubleshooting uploading documents in portals.
Uploading new versions of multiple filesCopy link to clipboard
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.
Using the uploadMethods parameterCopy link to clipboard
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.
For example, this can be helpful to ensure users do not upload photos of a signature instead of drawing their signature within the application.
Uploaded file size limitCopy link to clipboard
In portals, the size limit for uploaded files is 10 MB. Everywhere else, the file size limit is 1GB.
Saving a task as a draft with an uploaded fileCopy link to clipboard
If a user has uploaded a file to a task, they won't be able to save the task as a draft unless it is an offline-enabled task that they are viewing on Appian Mobile. They can remove the file or files to save the task as a draft.
Uploaded files are stored as temporary documents until submissionCopy link to clipboard
When a file is uploaded, the component updates with a temporary document representing the uploaded file. Between the upload and the 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 file upload is submitted.
If a file is uploaded but is never submitted, the temporary file is automatically deleted after 30 days.
If enabled in Admin Console, uploaded files are scanned for virusesCopy link to clipboard
If real-time virus scanning is enabled for file uploads in the Admin Console, the uploaded file will always be scanned for viruses, regardless of whether the virus scanning message is shown.
Some characters in file names are replacedCopy link to clipboard
If any of the following characters appear in a filename, they are replaced by underscores after submitting the file upload: \ / " ; : | ? ' < > *
.
ExamplesCopy link to clipboard
To experiment with examples, copy and paste the expression into an interface object.
File upload in a start form or taskCopy link to clipboard
This example shows how to use the file upload component in an interface that will be used in a start form or task.
Keep in mind that if you don't use this interface in a start form or task, on the Submit button, you would need to replace submit: true
with saveInto: a!submitUploadedFiles()
. See File upload outside a start form or task for more information.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
a!localVariables(
local!file,
a!formLayout(
label: "File Upload Form",
instructions: "Use this example in a start form or task",
contents: {
a!fileUploadField(
label: "Upload File",
/* Replace this with a constant of type Folder in your environment */
target: cons!FOLDER_CONSTANT,
value: local!file,
saveInto: local!file
)
},
buttons: a!buttonLayout(
primaryButtons: {
a!buttonWidget(
label: "Submit",
/* If you don't set the submit parameter to true, the signature will not be uploaded */
submit: true,
style: "SOLID",
loadingIndicator: true
)
},
secondaryButtons: {
a!buttonWidget(
label: "Cancel",
value: true,
saveInto: {},
submit: true,
style: "OUTLINE",
validate: false
)
}
)
)
)
Copy
Displays the following:
File upload outside a start form or taskCopy link to clipboard
This example shows how to use the file upload component outside of a start form or task using a!submitUploadedFiles()
in the saveInto parameter of a button. See a!submitUploadedFiles() for more examples.
Keep in mind that if you use this interface in a start form or task, on the Submit button you would need to replace saveInto: a!submitUploadedFiles()
with submit: true
. See File upload in a start form or task for more information.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
a!localVariables(
local!file,
local!submissionSuccessful,
local!errorCode,
{
a!fileUploadField(
label: "File Upload",
labelPosition: "ABOVE",
saveInto: local!file,
value: local!file,
/* Replace this with a constant of type Folder in your environment */
target: cons!AS_DOCUMENTS_FOLDER_POINTER
),
a!buttonArrayLayout(
buttons: {
a!buttonWidget(
label: "Submit",
style: "SOLID",
/* If you don't use a!submitUploadedFiles(), the signature will not be uploaded */
saveInto: a!submitUploadedFiles(
onSuccess: a!save(local!submissionSuccessful, true),
onError: {
a!save(local!submissionSuccessful, false),
a!save(local!errorCode, fv!error)
}
)
)
},
align: "END"
)
}
)
Copy
Displays the following:
File upload with the icon style and no filesCopy link to clipboard
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 uploadCopy link to clipboard
1
2
3
4
5
6
7
8
9
10
11
a!localVariables(
local!coverLetter,
a!fileUploadField(
label: "Cover Letter",
/* Replace this with a constant of type Folder in your environment */
target: cons!FOLDER_CONSTANT,
maxSelections: 1,
value: local!coverLetter,
saveInto: local!coverLetter
)
)
Copy
Displays the following:
Signature-capture only field on the Appian Mobile applicationCopy link to clipboard
1
2
3
4
5
6
7
8
9
10
11
12
a!localVariables(
local!signature,
a!fileUploadField(
label: "Signature",
/* Replace this with a constant of type Folder in your environment */
target: cons!FOLDER_CONSTANT,
maxSelections: 1,
value: local!signature,
saveInto: local!signature,
uploadMethods: "SIGNATURE"
)
)
Copy
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.
Using fv! variablesCopy link to clipboard
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.
Add one of the following parameter configurations to a file upload component to achieve the desired behavior.
Swap spaces for underscores in file namesCopy link to clipboard
1
fileNames: substitute(fv!files.name, " ", "_")
Copy
Set file descriptions to a value plus file indexCopy link to clipboard
1
fileDescriptions: "Application ABC-123 attachment " & fv!index
Copy
All files must be PDFsCopy link to clipboard
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)), {}),
""
)
)
Copy
No files may be PDFsCopy link to clipboard
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))),
""
)
Copy
Files may only be PNG or JPGCopy link to clipboard
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)), {}),
""
)
)
Copy
Files must be larger than 5MBCopy link to clipboard
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), {}),
""
)
Copy
Files must be smaller than 5MBCopy link to clipboard
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), {}),
""
)
Copy
Up to five files are allowedCopy link to clipboard
1
validations: if(length(fv!files) > 5, "Only 5 attachments are allowed", "")
Copy
Exactly five files are requiredCopy link to clipboard
1
validations: if(not(length(fv!files) = 5), "5 files must be attached", "")
Copy
At least five files are requiredCopy link to clipboard
1
validations: if(length(fv!files) < 5, "There must be at least 5 attachments", "")
Copy
Feature compatibilityCopy link to clipboard
The table below lists this component's compatibility with various features in Appian.
Feature | Compatibility | Note |
---|---|---|
Portals | Compatible | |
Offline Mobile | Compatible | |
Sync-Time Custom Record Fields | Incompatible | |
Real-Time Custom Record Fields | Incompatible | Custom record fields that evaluate in real time must be configured using one or more Custom Field functions. |
Process Reports | Incompatible | Cannot be used to configure a process report. |
Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |
Process Autoscaling | Compatible |
Old versionsCopy link to clipboard
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.