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 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 a!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.

Design guidance for incompatible and partially compatible functions

If an interface or expression rule that is a precedent of a portal uses an incompatible or partially compatible function, a design guidance recommendation will display. If you see this design guidance:

• For incompatible functions or components, refactor your expression to remove them.
• For partially compatible functions, create a custom integration to call the function from a web API.
• If the function or component will not evaluate in the portal, you don't need to do anything. For example, if you have logic that will use an incompatible function in a site but not a portal, the component should not evaluate in the portal.

Creating custom integrations for partially compatible functions

To use partially compatible functions in a portal, you can call the function in a web API and use an integration object in the portal interface to call the web API.

The integration and web API form a bridge that connects your portal to Appian and allows data to pass through. The integration is on one side—in your portal—and the web API is on the other side—in Appian.

The high level steps to create a custom integration in a portal are below. For more detailed steps that outline a similar process, see working with data using CDTs.

To use a partially compatible function in a portal:

1. Create a web API and call the function in the web API.
2. Create an API key and service account and give the service account Viewer permissions to the web API.
3. Create an HTTP connected system that uses API Key authentication.
   • For Header, enter appian-api-key.
   • For Value, use the API key you created.
4. Create an integration object.
   • Select Use a connected system and choose the connected system you created.
   • For URL, enter the URL from the web API you created.
5. In your portal interface, call the integration object using the rule! domain prefix.

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.

• To download documents, use the document download link component.
• To display images such as PNGs, use the document image component.
• To display documents such as PDFs, use the document viewer component.
• To display documents from another system, use the web content field component.
• To use the property information for a document, such as displaying a document name, use the document() function.
• To upload a file or signature using a file upload or signature component, use the a!submitUploadedFiles() function. See the linked pages for more information and examples.

There are a few things to keep in mind when uploading files in a portal, which are documented in the following sections.

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.

Uploading files in a portal

The following are some things to keep in mind when using file upload and signature components in a portal.

• To make sure files will be uploaded correctly in a portal, publish the portal and test the file upload on the portal website. See a!submitUploadedFiles() for more information on testing and troubleshooting uploading documents in portals.
• In portals, the size limit for uploaded files is 10 MB.

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.

Feedback