a!urlForPortal() Function

Returns a URL for a portal page. Use where a!pageLink() can't be used, like external systems and emails. See When to use the page link component to learn when to use each link type.

Parameters

a!urlForPortal( portalPage, urlParameters, locale )

Returns

Text

Using the function

The following sections cover important details about the a!urlForPortal() function.

Referencing portal pages

The portalPage parameter takes a reference to a portal page that is constructed using the portal! domain. See Reference Site and Portal Pages to learn how to construct a portal page reference.

Using a!map()

To create a list of the URL parameter names and values for the urlParameters parameter, use the a!map() function to create a list of the URL parameters as key-value pairs. Use the URL parameter name configured in the Rule Input Configurations grid as the key in the key-value pair.

Note that you can also use a dictionary.

For example:

1
2
3
4
5
6
urlParameters: a!map(
  /*URL parameter name = county, URL parameter value = "Fairfax"*/
  county: "Fairfax",
  /*URL parameter name = active, URL parameter value = true*/
  active: true
)

This example is for illustrative purposes only. It won't work if you copy and paste it into an expression.

Error handling

This table outlines scenarios that could cause a link to error. To avoid broken links, we've implemented certain error handling. This error handling behaves differently depending on if you use a!urlForPortal() or construct the links manually using plaintext URL parameters.

Additionally, if someone changes or deletes a character in an encrypted URL parameter string, all URL parameters that don't have a default value will be ignored.

Generated URL structure

The structure for the generated URL is:

https://[portal-domain]/[portal web address ID]/page/[page web address ID]?[encrypted or plaintext URL parameters]

For example, a URL with plaintext URL parameters might look something like:

https://statedot.appianportals.com/projectportal/page/projects?county=Fairfax&active=true

If the page was within a page group, the URL would display as:

https://statedot.appianportals.com/projectportal/group/transportation/page/projects?county=Fairfax&active=true

By default, URL parameters are encrypted in the generated URL. If Encrypt URL parameters is turned off for the portal page, the URL parameters will display in plaintext.

Examples

The following examples demonstrate the a!urlForPortal() function.

These examples reference portals from another environment and will error if you try to use them in yours. Use them as a reference only.

Link to a portal page

1
2
3
4
5
6
7
8
a!urlForPortal(
  /*Replace the portal page and URL parameters with valid references from your environment*/
  portalPage: portal!DOT Project Portal.pages.project-grid,
  urlParameters: a!map(
    county: "Fairfax",
    active: true
  )
)

If Encrypt URL parameters is turned on for the page, returns something like:

https://insurecorp.appianportals.com/dot/page/projects?$sp=AAAAAQAAAAAAAAABAAAAEJipwSTzHzI679DzFIjKqeml6sPuuyAWuAnrDIgMG7D5YVbpCLs1Aq5dZHWqbmLw2Z7wpMI6t6lnbmhP6yg7_4WSE_nNUi8WrhryW08

The encrypted characters for the URL parameter will change each time a!urlForPortal() is executed.

If Encrypt URL parameters is not turned on for the page, returns:

https://statedot.appianportals.com/projectportal/page/project-grid?county=Fairfax&active=true

Link to a portal page with a locale specified

When you know what locale the user will want, use the locale parameter to specify the locale in the link.

For example, imagine you have a portal that displays in both English and Spanish with English as the default. When users submit a request, you send them an email with a link to view the details of their request. For Spanish-language users you could automatically open the portal in Spanish by specifying the locale in the link.

1
2
3
4
5
6
7
8
9
10
11
12
a!safeLink(
  label: "VER SOLICITUD",
  uri: a!urlForPortal(
    /* Replace the portal page and URL parameters with valid references from your environment */
    portalPage: portal!DOT Portal.pages.service-request,
    urlParameters: a!map(
      requestId: ri!requestId,
      /* This sets the portal locale to Spanish using the "es" locale code */
      locale: "es"
    )
  )
)

Feature compatibility

Feedback