Design a Portal
This content applies solely to Appian Portals, which may require an additional license purchase.

Introduction

Appian Portals allows you to take advantage of the Appian low-code platform to design feature-rich experiences for your external users. They enable you to create public websites that are separate from Appian but still connected to the information and processes that are already stored in Appian.

Because portals run outside of the main Appian environment, they don't automatically connect to Appian. They are also special because your users are anonymous so you don't know anything about them right away, like their name, preferred language, or time zone.

Because of this, designing a portal is a bit different from designing an authenticated application. This page outlines some of the most important things to consider when designing a portal. This includes the capabilities that are and are not available in a portal, as well as some design and user experience considerations you should take into account when you are designing a portal.

Appian Portals is currently only supported for Appian Cloud customers. Additionally, if your environment is behind a VPN, you cannot connect a portal to it to read or write data.

See also

The way you work with data and documents in a portal is a little different than how you work with them in an authenticated Appian application. See the following pages for more information on how to work with data and documents in a portal.

Additionally, to define what to do when you think a bot is using your portal, check out Configuring reCAPTCHA.

Portal capabilities

After you publish a portal, it exists outside of your Appian environment. Because of this, the interfaces, expression rules, and other supporting objects that you use in your portal have some limitations.

There are certain platform capabilities that are partially compatible with portals. Because of the isolated architecture of portals, these capabilities will only work with a portal if you evaluate them in your Appian environment using an integration and web API. You couldn't use these capabilities directly in a portal the way you would in an authenticated Appian application.

For example, if you tried to call a partially compatible function like a!startProcess from a portal interface, it would error after you publish the portal and try to test it. However, you can still use the function if you connect to your Appian environment through an integration and web API. Learn how to use integrations and web APIs for partially compatible capabilities.

Additionally, there are a few capabilities that won't work in a portal at all.

The following table lists some common capabilities and whether they are compatible, partially compatible, or incompatible with portals. The compatibility of functions and components is also listed in the Appian Functions table. Keep this compatibility in mind when designing your portal to make sure you are using these capabilities in a way that works with portals.

Platform capability Portals compatibility Workaround
Direct connection to an external database using a data source connected system. Compatible - for external databases available at public IP addresses (preview feature). N/A
Connection to an Appian database, or a database behind a VPN. Partially compatible Connect to a web API object using an integration object. From the web API, use an Appian function to write or query data in your database.
Pre-built connected systems. Partially compatible Connect to a web API object using an integration object. From the web API, call an integration object using the desired connected system.
HTTP and OpenAPI connected systems. Compatible - using basic and API key authentication N/A
AWS Signature Version 4, Google Service Account, OAuth 2.0 authentication types. Partially compatible Connect to a web API object using an integration object. From the web API, call an integration object using the desired authentication type.
Appian-supported locales, time zones, and calendars. Compatible N/A
Site object. Incompatible If you want a navigation bar like a site, use a header content layout with a fixed header in your interface.
Decision objects. Partially compatible Connect to a web API object using an integration object. From the web API, call the decision object.
Component plug-ins. Incompatible None.
Function plug-ins. Partially compatible Connect to a web API object using an integration object. From the web API, call the function plug-in.
Components that need to connect to an Appian environment. Incompatible None.
Functions that need to connect to an Appian environment. Partially compatible/incompatible Connect to a web API object using an integration object. From the web API, call the function.

There are a few functions that will not work with this workaround. They are listed as incompatible with portals in the Appian Functions table.
Records-powered grids and charts. Incompatible Connect to a web API object using an integration object From the web API, query your record type. Then reference that data in charts and read-only grids.
Record actions and views. Incompatible Build a custom interface instead of using a record action or view.
Accessing the portal in the Appian Mobile application. Incompatible Access the portal from a mobile browser.
Offline mobile. Incompatible None.
Rule inputs. Compatible - but not in your parent interface. N/A
Tasks. Incompatible Your users should be authenticated if you need to send them a task
Uploading and downloading files. Compatible N/A
Using a portal as an embedded interface. Incompatible Link to the Portal from your website.

Design considerations for portals

Because creating a portal is a bit different from creating an authenticated application, there are some things you'll need to take into account when planning for and designing your portal.

Don't use rule inputs on the parent interface

Setting up a portal is similar to setting up a site. When you set up your site pages, you select one parent interface for each page. Similarly, when you publish a portal, you select one parent interface.

Additionally, just like with sites, you can only use local variables on the parent interface of a portal. But the child interfaces, expression rules, and other design objects can use both rule inputs and local variables.

To summarize:

  • Parent interface: The interface you select when you publish your portal; cannot use rule inputs.
  • Child interface: Any interface that is referenced by your main interface; can use rule inputs.

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 or Compatible, then choose Portals from the next dropdown list. To view the portal compatibility in the table, toggle on the Compatibility column.

Portal compatibility in function table

To use partially compatible capabilities, connect to them using a web API and integration

Because a portal can connect to your Appian environment through integrations and web APIs, you can use this method to access capabilities that can't be used directly in a portal.

This includes the following capabilities:

  • Partially compatible functions
  • Function plug-ins
  • Decision objects
  • Partially compatible authentication types
  • Pre-built connected systems.

To do this, follow similar steps to working with data in portals, but call your design object in your web API.

For example, if you want to create a portal that allows users to self register for an Appian account, you could use the a!startProcess function to kick off a process model to create a user.

process model

However, a!startProcess() is a partially compatible function. If you tried to call it from a portal interface, it would error after you publish the portal and try to test it. The good news is, you could use a web API to call a!startProcess().

Your web API expression could look something like this:

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
a!startProcess(
  processModel: cons!SPA_StartProcess,
  processParameters: a!fromJson(
    http!request.body
  ),
  onSuccess: a!httpResponse(
    statusCode: 200,
    headers: {
      a!httpHeader(name: "Content-Type", value: "application/json")
    },
    body: a!toJson(
      fv!processInfo
    )
  ),
  onError: a!httpResponse(
    statusCode: 500,
    headers: {
      a!httpHeader(name: "Content-Type", value: "application/json")
    },
    body: a!toJson(
      {
        error: "There was an error starting the process"
      }
    )
  )
)

Then you would create an integration object that uses the POST method to modify data and rule inputs for the first name, last name, and email address. Be sure to use a connected system object for authentication.

integration object

Then you can reference the integration in the saveInto parameter of your submit button.

1
2
3
4
5
6
7
8
9
10
11
...
a!buttonWidget(
        label: "Submit",
        saveInto: rule!SPA_startProcessIntegration(
            firstname: local!firstname,
            lastname: local!lastname,
            email: local!email
        ),
        style: "PRIMARY"
      )
...

You can modify this method to reference the other partially compatible capabilities that can be used with this work around.

Test both the interface object and the portal itself

As with all Appian applications, you should always fully test your interface objects to make sure everything is functioning correctly. Be sure to test all input and selection fields, as well as all queries.

With a portal however, it is also important to fully test your portal after it is published. Be sure to fill out all of the fields, whether they are required or not, and go through all of the steps in your portal.

This will help mitigate the following concerns:

  • The a!submitUploadedFiles() and a!verifyRecaptcha() functions only work in a published portal. You can't test them in the interface object itself. See Configuring reCAPTCHA for more information about how to test reCAPTCHA.
  • If your integration to the platform isn't set up properly, you may not notice until after you publish and test the portal. When you're testing the interface object in Appian Designer, the integration connection may still work, even if it isn't set up correctly.
  • The best way to make sure you are only using compatible capabilities, is to fully test the entire portal.

User experience considerations for portal interfaces

With portals you need to consider a user type that you don't deal with in an authenticated interface—anonymous users. These users will likely access your portal from many different locations on many different device types. Since the users aren't a part of your organization, you know a lot less about them than your typical Appian users. Additionally, since they aren't logged in, you don't automatically know information about them like their preferred language or time zone.

Design your interface to account for time zones and localization

Because users of your portal aren't logged in with a user account, you can't access their time zone and location preferences.

To create the best experience for your users across locations and time zones:

  • For any component that displays time or asks users to enter a time, always display the time zone that your portal is using.

    time zone.png

  • Create a separate portal for each language and include a way for users to choose their language.

    language selection

Portals use the primary locale, time zone, and calendar settings that are configured in the Administration Console for the environment.

Use responsive design

Keep in mind that your users will likely be accessing your portal from many different types of devices. Make sure you design your portal so that it looks good on any screen size. For more guidance, check out our content on Responsive Design.

responsive design example

Additionally, to change the design based on the page width, be sure to use the a!isPageWidth() function. The a!isNativeMobile() function will not work with portals since portals don't display in the Appian Mobile application. You can also use the stackWhen parameter in columns layouts and side by side layouts to make your design look great on any screen size.

Note that the page width for a portal is equivalent to "Full" in a site page.

If you create a header for a portal, consider using a fixed header

If you want a header for your portal, you can create one using a Header Content Layout component. Use this to create a navigation menu or to incorporate your logo and branding in a header.

When creating a header like this, we recommend using the isHeaderFixed parameter to fix your header to the top of the page.

portal with a fixed header gif

Open in Github Built: Fri, Sep 23, 2022 (01:18:20 PM)

On This Page

FEEDBACK