a!urlForPortal() Function

Function

a!urlForPortal( portalPage, urlParameters, locale )

Returns a URL for a portal page. Edit the page in the portal object to map the rule inputs to URL parameters, set default values, or opt out of encrypting URL parameters for the page.

See Use URL Parameters for Site and Portal Navigation for more information about URL parameters and how to use them to link to portal pages.

Parameters

Returns

Text

Usage considerations

Referencing portal pages

The portalPage parameter takes a reference to a portal page that is constructed using the portal! domain. This domain prefix is a direct object reference that removes the need to create a constant to reference a portal.

It's easy to construct a portal page reference since the portal! domain leverages typeahead to suggest a selection of existing portals. If you already know the name of your portal, you can even skip entering the domain and simply type the name of the portal for the domain and portal object reference to appear.

The portal object reference combined with . dot notation allows you to directly access portal pages, which are identified in the object reference by their web address identifier.

To reference a portal page:

1. Enter the portal! domain and select the portal.
2. Enter . after portal!<Portal Name> to autosuggest the portal pages.
3. Select pages to access the menu of pages configured in the portal object.
4. Select a page's web address identifier from the dropdown to append to the pages property.

For example, the reference below refers to the Projects page on the DOT Portal.

When you highlight a portal page from the dropdown, Appian automatically provides additional information about the page, including:

• Portal name.
• Page title.
• Page web address identifier.
• Interface used as the page content.
• Whether or not the page is configured to use encrypted URL parameters.
• URL parameters names that are enabled for the page.

You can also access this information in the expression documentation pane by clicking the portal page reference. Notice how the URL parameter names display under Enabled URL Parameter(s). This will come in handy when using the urlParameters parameter.

When using a portal page reference, Appian automatically shortens the reference to improve the readability of your expressions. To display the full reference, simply hover over it.

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

Portal object references are specific to each environment. If you copy and paste these examples into an interface or expression rule, they will not evaluate. Use them for 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 using a link field

You can link to a portal page using any component that a!safeLink can be used in. For example, to link to a portal page using a link component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
a!linkField(
  labelPosition: "COLLAPSED",
  links: {
    a!safeLink(
      label: "Active Projects in Fairfax County",
      uri: 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
        )
      )
    )
  }
)

This returns a link with label "Active Projects in Fairfax County" that uses the encrypted or plaintext link from the Link to a portal page example.

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