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 your 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.
• To upload, download, and view documents in your portal, check out Working with Documents in Portals.
• For more information on designing the best experience for your users, see portals design guidance.
• For a full list of what you can do in a portal, see Portal Capabilities.

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 primary interface for each page. Similarly, when you publish a portal, you select one primary interface.

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

To summarize:

• Primary interface: The interface you use as the content of your portal; cannot use rule inputs.
• Supporting interface: Any interface that is referenced by your primary 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.

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.

However, a!startProcess() is a partially compatible function. If you tried to call it from an interface for your portal, 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.

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.

Feedback