a!urlForSite() Function

Returns a URL for a site 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!urlForSite( sitePage, urlParameters )

Returns

Text

Using the function

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

Linking to sites across environments

This function makes it easy to link directly to site pages in other environments without hardcoding a link, which is fragile, or using constants, which is cumbersome.

The function automatically uses the domain from the environment from where the link is accessed.

For example, in a development environment, a link created with a!urlForSite() might look like https://dot-dev.appiancloud.com/projectsite/page/project-dashboard. But when you access the link from a production site, it would look something like https://dot.appiancloud.com/projectsite/page/project-dashboard.

Referencing site pages

The sitePage parameter takes a reference to a site page that is constructed using the site! domain. See Reference Site and Portal Pages to learn how to construct a site 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!urlForSite() 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://[site-domain]/[site 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.appiancloud.com/projectsite/page/project-dashboard?county=Fairfax&active=true.

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

https://statedot.appiancloud.com/projectsite/group/transportation/page/project-dashboard?county=Fairfax&active=true

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

Examples

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

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

Link to a site page

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

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

https://statedot.appiancloud.com/projectsite/page/project-grid?$sp=AAAAAQAAAAAAAAABAAAAEJipwSTzHzI679DzFIjKqeml6sPuuyAWuAnrDIgMG7D5YVbpCLs1Aq5dZHWqbmLw2Z7wpMI6t6lnbmhP6yg7_4WSE_nNUi8WrhryW08

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

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

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

Feature compatibility

Feedback