Linking to Portal Pages Using URL Parameters

Overview

There are times when you want to provide initial values for a portal page. For example, you may want give users a way to open a grid with filters already applied. Rule inputs allow you to pass data into an interface to set these initial values. URL parameters allow you to pass data into these rule inputs through links.

This page provides the following information about URL parameters:

• What they are.
• How they work with rule inputs.
• What to use them for.
• How to set up, update, and use them.
• Usage considerations.

What are URL parameters?

URL parameters allow you to pass information to a web page. They can be used to tell a web page what to display or how to behave.

URL parameters typically follow a question mark (?) in a URL. For example, if you search https://careers.appian.com/jobs/ for jobs with the keyword software in Mclean, Virginia, the link updates to:

1
https://careers.appian.com/jobs/`?search=software&location=McLean%2C+Virginia`

You could send this link to someone else and when they click it, the results will only display software jobs in McLean.

In this example, the first URL parameter is search=software and the second URL parameter is location=McLean%2C+Virginia. Note that %2C replaces the comma.

URL parameters can also work with portal pages. They are just web pages after all.

How URL parameters work with rule inputs

Rule inputs allow you to pass data to an object. For example, you can use a rule input in an interface to determine what information displays when it first loads. This is how values are passed from a process model into an interface.

In portals, when you use an interface with a rule input as a portal page, you can set the value of the rule input using a link with URL parameters.

For example, imagine you have a portal interface with a rule input that is used for a grid filter. You can create a link that will use a URL parameter to set the value of the rule input using a!urlForPortal(). Whenever a user clicks the link, the grid loads and is automatically filtered using the value of the URL parameter. For an in-depth walkthrough, see Using URL parameters to link to a portal page.

Setting default values for rule inputs

When you're configuring rule inputs for a page, you can choose to set a default value for each rule input.

You may want to use a default value to:

• Provide a back up value in case the URL parameter is ignored due to error handling.
• Set the initial value for a rule input whenever the page loads.

The rule input will use the default value when:

• A user accesses the page via the header bar in the portal.
• A link doesn't use the URL parameter.
• A user changes or deletes any character in the encrypted URL parameter string.
• Someone constructs a plaintext link that would otherwise ignore a URL parameter due to error handling, such as if they misspell the URL parameter name.

If the default value isn't configured and a URL parameter doesn't provide the value, the rule input value is null.

When to use URL parameters

You can use URL parameters whenever you want a portal page to load specific information. For example, you can use them to:

• View information in a submitted case.
• Link to a pre-filtered interface.
• Pre-populate a form.

This section covers several scenarios that URL parameters are especially useful for. To help you visualize how these could work in a real-world scenario, we'll use a Department of Transportation (DOT) portal as a fictional example.

Viewing submitted information

In some scenarios, you may want users to see the results of a submitted form so they can track the status of their submission or follow up on it. With URL parameters, you can create a link that allows a user to view information they submitted.

Example: View status of pothole repair request

After a user completes a request to fix a pothole, the DOT portal sends them an email with a link to their request so they can view its status.

Example: Send a survey to a user using a unique link

After attending a defensive driving class, a user receives an email with a link to a survey asking them to evaluate the course. The link is unique to the user and is automatically associated with the course they attended.

Linking to a pre-filtered interface

You can use URL parameters to create a link to a grid or report that automatically filters the content so users can quickly view the most relevant information.

Example: Filter a grid by a user's county

When a user clicks a link for project information for their county, a project grid opens that is automatically filtered by their county.

Pre-populating a form

You can use URL parameters to create a form that is pre-populated with information about the request.

Example: Pre-populating a form with information about a specific class

When a user clicks a link to sign up for a specific driver safety class, the form automatically populates with information about the class, including date, time, and location.

Using URL parameters to link to a portal page

Set up URL parameters

To allow your portal to use URL parameters, you'll need to:

1. Add rule inputs to the interface.
2. Configure the rule inputs on the portal page.
3. Add a service account if using encrypted URL parameters, then publish the portal.

The sections below walk you through each step.

Step 1: Add rule inputs to the interface

To configure URL parameters on your portal, your interface must first have rule inputs configured.

Only certain rule inputs can be used to link to portal pages using URL parameters. See Rule inputs that can be used to set initial values for the requirements.

To add rule inputs to the interface you'll use as a portal page:

1. In the Rule Inputs pane of the interface, click New Rule Input.

2. Configure the rule input properties:

   Property	Value
   Name	The name of the rule input.
   Description	(Optional) A description of the rule input's purpose.
   Type	Use a supported data type: Boolean Date Date and Time Number (Decimal) Number (Integer) Text Time
   Array (multiple values)	Leave deselected

3. Click CREATE.
4. Repeat the above steps to create additional rule inputs.
5. Use the rule inputs to set values on the interface.
6. Click SAVE CHANGES.

Step 2: Configure the rule inputs on the portal page

Next, you need to configure the rule inputs on the portal page.

To add a new page using an interface with rule inputs:

1. Open the portal object and add a page.
2. For Content, select the interface that you added rule inputs to. The Rule Input Configuration displays.
   • Tip: Hover over the tooltip next to the rule input name to view the rule input description.

   

3. Configure the Rule Input Configuration properties. If you don't make any modifications to these properties, the defaults will be used.

   Property	Description	Default
   Encrypt URL parameters	Determines whether to use encrypted or plaintext URL parameters. To help keep data secure, URL parameters are encrypted by default. See Using URL parameters securely for more information about when to use encrypted versus plaintext URL parameters.	Selected
   Rule Input	The rule inputs from the selected interface. Only rule inputs that can be used to set initial values will appear.	Read only
   Enable in URLs	To help keep your data secure, only enable the rule inputs that you need to use with URL parameters. This only appears when Encrypt URL parameters is deselected so that you can opt in to using only the URL parameters that are safe to display in plaintext.	Toggled off
   URL Parameter Name	The name used when constructing links to the portal page. You can change this from the default if you want to make sure existing links don't break, or if you just want to make the name shorter or more clear.	Rule input name
   Default Value (optional)	The value to use whenever the URL doesn't provide a value. See Using default values for more information. The evaluated default value can only be 100 characters or less. Otherwise, the default value will be ignored.	Null

4. Click DONE.

Step 3: Add a service account if using encrypted URL parameters, then publish the portal

If Encrypt URL parameters is selected for any portal page, the portal object must have a service account. Additionally, portals have to be published before you can link to them.

To add a service account to the portal and publish it:

1. In the portal object, if there isn't already a service account, go to the Service Access section and add a service account.
2. If necessary, go to the Configurations section and turn on the Published toggle.
3. Click SAVE CHANGES and make sure the portal publishes successfully.

Updating rule inputs in a portal page

If you add, rename, or delete rule inputs from an interface used as a portal page, you will need to edit the portal page to update the rule input configurations. You will also need to republish the portal.

This helps ensure that:

• Links to the portal page will continue to work, even if their rule inputs are renamed.
• New rule inputs can be used with URL parameters.

This section provides instructions for adding, renaming, and deleting rule inputs in interfaces that are being used as a portal page.

Adding a new rule input

After you add a new rule input to an interface that is being used in a portal page, you won't be able to use it with a URL parameter until after you edit the portal page and republish the portal.

To add a new rule input to be used on a portal page:

1. In the interface, add a rule input.
2. In the portal object, locate the page that uses the interface that you added rule inputs to.
   • Tip: Pages with rule inputs that can be used with URL parameters are identified with Has rule input configurations.

3. Click to edit the page.

   

4. Configure the Rule Input Configuration properties for the rule input. If you don't make any modifications to these properties, the defaults will be used.
   • Tip: New rule inputs are identified by the NEW tag. Hover over the tooltip next to the rule input name to view the rule input description.

   Property	Description	Default
   Encrypt URL parameters	Determines whether to use encrypted or plaintext URL parameters. To help keep data secure, URL parameters are encrypted by default. See Using URL parameters securely for more information about when to use encrypted versus plaintext URL parameters.	Selected
   Rule Input	The rule inputs from the selected interface. Only rule inputs that can be used to set initial values will appear.	Read only
   Enable in URLs	To help keep your data secure, only enable the rule inputs that you need to use with URL parameters. This only appears when Encrypt URL parameters is deselected so that you can opt in to using only the URL parameters that are safe to display in plaintext.	Toggled off
   URL Parameter Name	The name used when constructing links to the portal page. You can change this from the default if you want to make sure existing links don't break, or if you just want to make the name shorter or more clear.	Rule input name
   Default Value (optional)	The value to use whenever the URL doesn't provide a value. See Using default values for more information. The evaluated default value can only be 100 characters or less. Otherwise, the default value will be ignored.	Null

   

5. Click DONE.
6. Click SAVE CHANGES and make sure the portal publishes successfully.

Renaming a rule input

If you rename a rule input in an interface that is being used in a portal page, the Rule Input Configuration grid will add a new rule input and ask you to remove the old rule input.

Since rule inputs are mapped to URL parameter names, you can update the URL parameter name of the new rule input to match the old URL parameter name. This makes sure existing links will continue to work. If you don't update it, the URL parameter will be ignored in any links that use the old URL parameter name.

For example, let's say you have a rule input and URL parameter both named active. If you update the rule input name to isActive, a new rule input will appear in the Rule Input Configuration grid. To ensure existing links to the page continue to work, you can update the URL parameter name for the new isActive rule input to active.

To rename a rule input that is configured on a portal page:

1. In the interface, click the name of the existing rule input. The Edit Rule Input dialog appears.
2. Rename the rule input and click OK.
3. Click SAVE CHANGES. The Updated Rule Inputs dialog displays.

4. Click the portal object name to open it so you can update the URL parameter name.

   

5. In the portal object, click next to the page that uses the interface.
6. To make sure existing links will still work if they use the URL parameter name, update the new URL parameter name to match the old URL parameter name.
   • Tip: Old rule inputs are identified by the icon and new rule inputs are identified by the NEW tag. Hover over the tooltip next to the rule input name to view the rule input description.

   

7. In the Rule inputs were changed in the interface message, click REMOVE OLD RULE INPUTS.

   

8. Click DONE.
9. Click SAVE CHANGES and make sure the portal publishes successfully.

Deleting a rule input:

If you delete a rule input from an interface that is being used in a portal page, you need to delete the rule input from the portal page too.

If there are existing links that use the URL parameter that was mapped to the deleted rule input, the URL parameter will be ignored.

To delete a rule input that is configured on a portal page:

1. In the interface, click the name of the existing rule input.
2. In the Edit Rule Input dialog, click DELETE.
3. Click SAVE CHANGES.
4. Open the portal object and click next to the page that uses the interface.
5. In the Rule inputs were deleted from the interface message, click REMOVE OLD RULE INPUTS.
   • Tip: Old rule inputs are identified by the icon.

1. Click DONE.
2. Click SAVE CHANGES.

Use URL parameters in links to the portal page

Now that you've configured your interface and portal, you can link to your portal using URL parameters.

There are several places you can link to a portal from, including:

• An interface or expression rule.
• A process model.
• Another portal.
  • Any portal that links to another portal using a!urlForPortal(), must have a service account configured.
• An external website.
  • We won't cover this in this section. For more information about methods for linking to a portal from an external website, see Linking from an external website.

To link to a portal page using encrypted URL parameters, you'll use a!urlForPortal(). This function allows Appian to encrypt URL parameters and allows you to keep your links up to date if the URL ever changes. This can happen if you change the web address identifiers for your portal or portal page, or if you rename the rule inputs.

To use a!urlForPortal() to link to a portal:

1. In an interface, expression rule, or expression in a process model, enter a!urlForPortal().
2. For the portalPage parameter, reference a portal page using the portal! domain.
   • Enter portal! to see a list of portals. Select a portal from the list.
   • Enter a period (.) to see a list of portal pages. Select a page from the list.
3. For the urlParameter parameter, use a!map() to list your URL parameter names and values as key-value pairs. For example, a!map(key1: value1, key2: value2)

   • Tip: Click the portal reference to view the URL parameter names. They are listed in the expression documentation pane under Enabled URL Parameter(s).

     

Example: a!urlForPortal()

If the following example used plaintext URL parameters, it would return something like:

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

Note that if your portal has only one page, /page/[page web address ID] won't display in the URL. However, if you manually add /page/ followed by the web address identifier, the link will still work.

1
2
3
4
5
6
7
a!urlForPortal(
  portalPage: portal!DOT Project Portal.pages.projects,
  urlParameters: a!map(
    county: "Fairfax",
    active: true
  )  
)

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

Usage considerations

Rule inputs that can be used to set initial values

You can add any rule input type to interfaces added as a portal page. However, not all rule inputs can be used to set initial values for portal pages through URL parameters and default values. Rule inputs that aren't supported won't display in a portal page's Rule Input Configuration grid.

There are three basic considerations to determine if a rule input can be used with URL parameters and default values:

• The rule input must be of the following primitive system data types:
  • Boolean
  • Date
  • Date and Time
  • Number (Decimal)
  • Number (Integer)
  • Text
  • Time
• The rule input cannot be configured as an array.
• The rule input must be in the interface that is added as a portal page. Rule inputs that are in a precedent of a portal page cannot be used with URL parameters or default values.

Using URL parameters securely

To help keep your data secure, URL parameters are encrypted by default. You have the option to enable plaintext URL parameters, which you should only do if absolutely necessary. Read on to understand the difference between encrypted and plaintext URL parameters and when to use each.

Using encrypted URL parameters

When Encrypt URL parameters is selected, humans cannot read or manipulate the URL parameters. This prevents the average user from manipulating the URL to inadvertently or nefariously expose data not intended for them.

URL parameters should be encrypted unless they absolutely need to be plaintext. This is particularly important when passing in identifying information, such as an access code.

When Encrypt URL parameters is selected, links to the portal page can only be constructed using a!urlForPortal(). This means encrypted URL parameters can't be used to link directly to a portal page from an external website. See Linking from an external website for guidance.

Using plaintext URL parameters

When Encrypt URL parameters is deselected, all URL parameters use plaintext. This means that users can read and manipulate the parameters, which could expose data that isn't intended for them.

Don't enable plaintext for URL parameters that have values that could be manipulated to expose sensitive data that isn't intended for the user. For example, values that are predictable, like sequential record IDs.

If you disable Encrypt URL parameters, you must opt in to using URL parameters for each rule input on the portal page. Only turn on Enable in URLs for rule inputs that you need to use with URL parameters.

You might want to use plaintext URL parameters when:

• You're linking to the portal from an external website.
• You're using a third-party web service that needs to pass an exact value.

Keeping links to portals up to date

The following outlines how links to portal pages can change and how we help you keep them up to date. As you can see, using a!urlForPortal() offers a few different ways to keep your links up to date. Because of this, we recommend using a!urlForPortal() whenever possible and avoid constructing links manually, even when using plaintext.

We also automatically republish portals that link to other portals in certain situations to make sure that these links are kept up to date when the linked portal is updated.

Linking from an external website

Using encrypted URL parameters to link to a portal page from an external website isn't as straightforward as using plaintext URL parameters.

Encrypted URL parameters must be constructed using a!urlForPortal(). Because this encryption is specific to an environment, you can't construct a link in a development environment and modify it to be used in a production environment. You need to use a!urlForPortal() in a production environment to get an encrypted link for a production portal.

Because of this, if you need to use URL parameters to link to a portal page from an external website, we recommend using plaintext URL parameters, as long as you can use them securely.

If you must use encrypted parameters, you can use a web API that uses a!urlForPortal() to construct the link and invoke the web API from your external website.

Feedback