The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
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:
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.
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.
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:
The rule input will use the default value when:
If the default value isn't configured and a URL parameter doesn't provide the value, the rule input value is null
.
Tip: If the URL has the URL parameter name without a value, such as dot.appianportals.com/dot/page/projects?county=
, the rule input value will be null, not the default value.
You can use URL parameters whenever you want a portal page to load specific information. For example, you can use them to:
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.
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.
Note: Don't create portals that allow users to update information in a form they already submitted. If users need to update information they submitted, they should have an Appian account and update the information through a site rather than a portal.
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.
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.
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.
When a user clicks a link for project information for their county, a project grid opens that is automatically filtered by their county.
You can use URL parameters to create a form that is pre-populated with information about the request.
Note: Don't use this method to pre-populate user-specific information on a form in portals. Portals are intended for unauthenticated users to fill out generic forms.
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.
To allow your portal to use URL parameters, you'll need to:
The sections below walk you through each step.
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:
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:
|
Array (multiple values) | Leave deselected |
Next, you need to configure the rule inputs on the portal page.
To add a new page using an interface with rule inputs:
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 |
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:
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:
Tip: This only affects rule inputs that can be used to set initial values on portal pages. Other rule inputs don't need to be updated in the portal page if they change.
This section provides instructions for adding, renaming, and deleting rule inputs in interfaces that are being used as a portal page.
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:
Click to edit the page.
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 |
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:
Click the portal object name to open it so you can update the URL parameter name.
In the Rule inputs were changed in the interface message, click REMOVE OLD RULE INPUTS.
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:
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:
a!urlForPortal()
, must have a service account configured.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:
a!urlForPortal()
.portal!
domain.
portal!
to see a list of portals. Select a portal from the list..
) to see a list of portal pages. Select a page from the list.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).
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.
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:
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.
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.
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:
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.
How portal links change | How they are kept up to date |
---|---|
Changing the web address identifier for a portal or portal page. | Referencing a portal page using the portal! domain in a!urlForPortal() automatically uses the most recent web address identifier. |
Turning URL parameter encryption on or off for a portal page. | Using a!urlForPortal() automatically takes care of switching between encrypted and plaintext parameters when the Encrypt URL Parameter setting is changed for a portal page. |
Renaming a rule input that is used with URL parameters. | Update the new rule input's URL parameter name to match the old rule input's URL parameter name. See Renaming a rule input for instructions. |
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.
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.
Linking to Portal Pages Using URL Parameters