Portal Best Practices

Introduction

Appian Portals allows you to reach any audience your organization works with, without requiring them to log in. You can use the low-code tools you already know to create web apps that connect portal users to the information and processes in Appian.

Creating a portal is a bit different from creating a site. Portals run in a service that is separate from your Appian environment, but can be connected to your Appian applications, data, and workflows. Because of this, there are some things you'll need to take into account when planning for and designing the functionality of a portal. This page provides these best practices.

See also

• To learn how to write and query data in portals, see Working with Data in Portals.
• For more information on designing the best experience for your portal users, see the portal design guidelines.
• For a full list of what you can do in a portal, see Portal Capabilities.

Don't use rule inputs on interfaces added as pages

Just like with sites, the interfaces you add as pages in your portal cannot contain rule inputs. However, they can reference other objects that use rule inputs. If you select an interface with rule inputs, you'll receive a validation message.

Don't use incompatible functions and components

When you're designing an interface for a portal, you can use most of the components, functions, and designs that you know and love.

However, there are some components and function that are incompatible with portals.

To find out if a function is compatible with portals, use the filters on the Appian functions table.

Just change the dropdown list from Any Compatibility to Incompatible, Partially Compatible, or Compatible, then choose Portals from the next dropdown list. To view the portal compatibility in the table, toggle on the Compatibility column.

To use partially compatible capabilities, connect to them using a custom integration

Some capabilities are partially compatible with portals. This means you can still use them in a portal, as long as you connect to them using integration and web API objects.

Some examples of partially compatible capabilities:

• Partially compatible functions, like urlforrecord().
• Function plug-ins.
• Decision objects.
• Partially compatible authentication types.
• Pre-built connected systems.

To work with these capabilities in a portal, you connect the portal to the Appian environment by creating a custom integration using an integration and web API. Just follow similar steps to working with data using CDTs, but call the design object in a web API. You can modify this method to reference the other partially compatible capabilities that don't work directly in a portal.

Working with processes

Portals can use a!startProcess() in an interface to start a process. However, they cannot use any other method to start a process, such as through a start form or record action.

The portal service account must have at least Initiator permissions to the process model in order to start the process.

For an example of how to start a process in a portal, see Working with Data in Appian.

Working with documents

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 following components as you normally would.

• Use the document download link to download documents.
• Use the document image to display images such as PNGs.
• Use the document viewer to display documents such as PDFs.
• Use the web content field component to display documents from another system.
• Use the document() function to use the property information for a document, such as to display a document name.

Submitting files is also similar, with a few caveats that are outlined in this section.

Give the portal service account access to the documents

Whether you are setting up your portal to view, download, or upload documents, make sure you set up the service account permissions correctly so that the portal has the required access.

To download or view documents in a portal, use a document constant

When referencing documents in a portal, we recommend that you use a constant to serve the document directly from the portal. The constant must be of type Document. 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.

See the document download link, document image, and document viewer pages for specific examples of using a constant to download and view documents.

Best practices for submitting uploaded files

The following are some best practices to keep in mind when submitting uploaded files.

When using a file upload or signature component, add a!submitUploadedFiles() to the submit link or button

Configuring a file upload in your portal is very similar to configuring a file upload in a site, with one difference: you need to use the a!submitUploadedFiles() function to submit the file.

When you add the file upload or signature component to a portal interface, add the a!submitUploadedFiles()function to the saveInto parameter of a submit link or button. If you don't, the submission will not go through and the file will not upload to Appian.

When a user uploads a file using the file upload or signature component, the portal places the file in a temporary folder and saves the document ID in the component's saveInto parameter. As long as the submitUploadedFiles() function is in the saveInto parameter of a submission link or button, the the uploaded files are saved to the specified target folder when the user clicks the submission link or button.

See the a!submitUploadedFiles() function page for examples of how to submit uploaded files in a portal.

Test uploaded file submissions in a published portal

The a!submitUploadedFiles() function only functions in a published portal. If you try to test uploaded files in an interface object, it may seem to work, even if it isn't set up correctly. To test the uploaded file submission, publish your portal and test it in the portal itself.

Uploaded file size limit is 10 MB

When designing your portal, keep in mind that uploaded files can be no larger than 10 MB. You don't need to add a validation for this because the portal automatically includes a validation for uploaded file size.

To write document IDs through an integration, use the correct integration input

To write document IDs from uploaded files to a database through an integration, the integration input that you're writing must be of type Number(Integer), not Document. An incorrect type can cause the data and document IDs to not save properly.

Querying data that was previously submitted in your portal

Your users may need to come back to your portal at different times to access data that they've previously submitted using your portal. They might need to check on the status of their application or filed claim. To give them access to this data, set up a workflow that allows them to enter a value that triggers a query to retrieve their data.

Possible values could include:

• A unique code.
• A claim or application number.

You can provide values like a code or number in a variety of ways, here are a couple of ideas:

• Send it in a follow-up email sent from a process.
• Show it in the confirmation step of a wizard within your portal.

Be aware that this type of design should not be used to access information that a user would typically have to sign in to a user account to access. This workflow is different from a "sign in" experience and should not be designed to imply or be referred to as such. Additionally, keep in mind that certain functionality such as automatic sign-outs or session time-outs are not supported.

Feedback