Overview

Documents are an important part of many Appian workflows. Whether you want to provide documents to download, show a PDF, or provide a way for customers to upload their files, Portals connects you, your users, and all the necessary information to get their tasks done.

With a practically indistinguishable user experience from the rest of Appian, you can support your users interactions with documents through a portal using the a!fileUploadField(), a!documentDownloadLink(), and a!documentImage().

Uploading files in a portal

Portals can be used to fit a wide range of your organization's needs, many of which may require users to upload documents. Whether your users are applying for grants, submitting onboarding documents, or creating an accident claim, uploading documents to a process or record is a vital part of your application's workflow.

Using file uploads in your portal is very similar to using file uploads in a standard interface or application, with a few minor differences.

When a user uploads a file using the file upload or signature components, the portal places the file in a temporary folder and saves the document ID in the component's saveInto parameter. The user submits the uploaded files using the a!submitUploadedFiles function in the saveInto parameter of a submission link or button. Once submitted, the uploaded files are saved to the specified target folder.

Use the following function variables as you normally would with any other file upload or signature components:

• fv!file.name
• fv!file.size
• fv!file.extension
• fv!file.index

When uploading files in a portal, files can be no larger than 10 MB.

The submit uploaded files function

The a!submitUploadedFiles() function connects the uploaded files in any a!fileUploadField or a!signatureField components in your portal with their target folder in Appian. This function can only be used inside the saveInto parameter of components and it works best when used in submit links and buttons.

To learn more, check out a!submitUploadedFiles.

Example: Upload a file in a portal

This expression should only be used as an example and should not be used to test the a!submitUploadedFiles() function. If you copy and paste the expression into an expression editor, the a!submitUploadedFiles() function will not operate.

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
a!localvariables(
local!file,
  {
    a!fileUploadField(
      label: "Supporting Image",
      value: local!file,
      saveInto: local!file,
      target: cons!myFolder,
      maxSelections: 1,
      validations: if(
        or(fv!files.extension = { "png", "jpg" }),
        null,
        "Please upload a valid image type: png or jpg"
      )
    ),
    a!buttonArrayLayout(
      buttons: {
        a!buttonWidget(
          label: "Submit",
          submit: true,
          style: "PRIMARY",
          saveInto: a!submitUploadedFiles()
        )
      },
      align: "END"
    )
  }
)

Downloading files and viewing document images in a portal

Whether your users need to download documents from in-flight processes or view data in PDFs, your portal enables users to download and view information seamlessly.

The developer and user experience for downloading files and viewing document images in a portal is the same as it is in the rest of Appian. Simply use the a!documentDownloadLink() and a!documentImage() components as you normally would, complete with all the normal parameters. Note that when using a constant to reference a document, you must use a constant of type document.

When referencing documents in a portal, we recommend that you use a constant to serve the document directly from the portal. You can use the document ID instead, but that method is less performant than using a constant because the portal must query Appian for the document.

Example: Downloading files in a portal using a constant

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  a!linkField(
    label: "Download document",
    labelPosition: "ABOVE",
    links: {
      a!documentDownloadLink(
        label: "Document Link",
        document: cons!myDocument
      )
    }
  ),
  a!linkField(
    label: "Download another document",
    labelPosition: "ABOVE",
    links: {
      a!documentDownloadLink(
        label: "Document Link",
        document: local!data[1].documentID
      )
    }
  )
}

Example: Viewing document images in a portal using a constant

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  a!imageField(
    label: "View a document image",
    labelPosition: "ABOVE",
    images: {
      a!documentImage(
        document: cons!myDocument
      )
    }
  ),
  a!imageField(
    label: "View another document",
    labelPosition: "ABOVE",
    images: {
      a!documentImage(
        document: local!data[1].documentID
      )
    }
  )
}

Security and service accounts

Whether your users are uploading, downloading, or viewing files in your portal, they need to have permissions to provide and access documents through your portal. For viewing and downloading files, they need Viewer permissions to the folders that contain the files. For uploading files, they will need Editor permissions to the target folders that the files will be uploaded to.

Since portal users are external and don't have individual Appian user accounts, grant them permissions to your documents and folders using a service account and end-user groups.

To give users access to documents and folders:

1. Use an existing service account or create a new one by adding an existing user to the Service Accounts group.
2. Add that same service account to your Users group in your application.
3. Give the Users group the correct permissions to your document folders or create new end-user groups with more granular permissions to your document folders.
4. Add your service account to the Portal Publishing Manager.

If you're already using a service account for data services in your portal, you can use the same service account that you set up with your API key or the service account used with the data source connected system for your external database as the service account for your portal.

For more information about using service accounts with your portal, see Service Accounts in Portals.

Testing

Be sure to fully test all parts of your document services in your portal at scale. Test your portal both before and after publishing to make sure your users can upload or download documents correctly. Some connections can't be tested until after publishing.