Query Parameter node

The Query Parameter node lets you insert query parameter values from a journey URL into configurable node state properties. This lets you customize journeys based on the query parameter values.

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node takes its inputs from the journey URL and maps each query parameter to a property in the node state. For multi-valued parameters, the node delimits the parameters by a comma (,) symbol. In this case, the value assigned to the node state property is a comma-delimited list of items.

The node doesn’t read input from the state.

The node has no required predecessor nodes.

Dependencies

None.

Configuration

Property Usage

Property	Usage
Allowed query parameters	List the query parameters the node can obtain from the URL and map them to a property in the node state: Click Add. In the Key field, enter the query parameter name. In the Value field, enter the node state property that will hold the value of this query parameter. This field sets an allowlist of parameters the node can pull into the node state. Exercise caution when you create this list to avoid injecting harmful data into the node state. If a query parameter in the URL isn’t in this list, the node ignores it. To edit an entry, click the [.label]#Pencil# icon (). To remove an entry, click the [.label]#Delete# icon ().
Allowed query parameters to be delimited	Specify the allowed query parameters that can take multiple values and whose values you want to store in the node state in a comma-delimited list; for example, `["yellow", "green", "red"]`. Enter the query parameter name in the Add value field and click Add. If you don’t delimit the values of a multi-valued query parameter, the node stores the values in the node state as a single string value; for example, `["yellow, green, red"]` . To edit an entry, click the [.label]#Pencil# icon (). To remove an entry, click the [.label]#Delete# icon ().

Allowed query parameters

List the query parameters the node can obtain from the URL and map them to a property in the node state:

Click Add.
In the Key field, enter the query parameter name.
In the Value field, enter the node state property that will hold the value of this query parameter.

This field sets an allowlist of parameters the node can pull into the node state. Exercise caution when you create this list to avoid injecting harmful data into the node state.

If a query parameter in the URL isn’t in this list, the node ignores it.

To edit an entry, click the [.label]#Pencil# icon ().

To remove an entry, click the [.label]#Delete# icon ().

Allowed query parameters to be delimited

Specify the allowed query parameters that can take multiple values and whose values you want to store in the node state in a comma-delimited list; for example, ["yellow", "green", "red"].

Enter the query parameter name in the Add value field and click Add.

If you don’t delimit the values of a multi-valued query parameter, the node stores the values in the node state as a single string value; for example, ["yellow, green, red"] .

To edit an entry, click the [.label]#Pencil# icon ().

To remove an entry, click the [.label]#Delete# icon ().

Outputs

If the Allowed query parameters setting has one or more values, the node adds the values of the listed URL parameters to the corresponding properties in the node state.
If the Allowed query parameters setting has a value but that query parameter isn’t present in the URL, the node sets an empty list ([]) in the corresponding node state property.
If an allowed query parameter is also listed in the Allowed query parameters to be delimited, the node sets the values of the listed URL parameter in the node state as a comma-delimited list.

The node URL-decodes query parameters before putting them into the node state.

If a query parameter includes %2C, the node puts this value into the node state as a comma (,). If the query parameter is included in the Allowed query parameters to be delimited the node interprets %2C as a comma delimiter.

The node decodes the plus symbol (`) as a _space_. If you need a ` in a query parameter value, encode it as %2B in the URL.
Values stored in the node state can override values in the authentication journey.

Take special care when you configure this node so that you don’t unintentionally override parameters such as usernames and passwords.

The output of this node isn’t under the control of the node itself. Encode sensitive values appropriately, either at node output, or before the values are used later in the journey.

Outcomes

Single outcome that passes an updated node state to the next node in the journey.

Errors

No parameters configured - this node is redundant

The node logs this error if you include it in a journey but don’t configure any Allowed query parameters.
Cannot delimit parameter if it is not configured as a parameter to be stored in node state

The node logs this error if you add a parameter to the list of Allowed query parameters to be delimited but not to the list of Allowed query parameters.

Examples

Use the Query Parameter node to customize a journey based on query parameters in the URL. The following scenarios illustrate how this node might be used:

Customized branding

An organization has several brands that use the same journey. Use this node to customize the brand the user sees, based on the query parameters.

Consider the following authentication journey:

Authentication journey using query parameter node

The configuration of the Query Parameter node maps the brand query parameter to a property in the node state named stateBrand
The user accesses the journey at a URL that can be one of the following:
- https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=Login
- https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=Login&brand=yellow
- https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=Login&brand=red
The Query Parameter node obtains the value of brand from the URL and sets that value in the stateBrand property in the node state; for example, stateBrand=yellow

The journey progresses to the scripted decision node that includes the following script:

var brand = JSON.parse(nodeState.get('stateBrand'));

if (brand.indexOf("yellow") >= 0) {
  outcome = "yellow";
} else if (brand.indexOf("red") >= 0) {
  outcome = "red";
} else {
  outcome = "regular";
}

The script routes the journey to one of three outcomes; yellow, red, or regular, depending on the value of the stateBrand property.
The outcomes direct the user to a custom branded Login journey configured in an Inner Tree Evaluator node; for example:
Each Inner Tree Evaluator node routes the end user to a login journey that uses a custom brand.

Redirection from an external system

An external system redirects a user to this authentication journey. The external system must share information about the user with the journey. Use this node to obtain the relevant query parameters and inform the journey of their values.