URL JavaServer Page tag

The URL JavaServer Page (JSP) tag provides a means to include a Uniform Resource Locator string into the output HTML produced by stream processing.

The URL tag has options related to navigation, target frames, and the primary page. Options promote transaction integrity between the client browser session and the requestor state on the Pega Platform server. You can use the URL tag to avoid synchronization problems that can arise if a user clicks the browser's Back button rather than using navigation provided in HTML displays.

Wherever you insert an anchor or a submit button into your HTML, you can use the URL tag. If you use the URL tag with a submit button, work with the FORM tag as well.

Here is an example of the URL tag used with an anchor.

<A HREF="<pega:url value="pyStream=myStream" >
<option name="long">
</pega:url >" >
<B>My Anchor Text</B></A>

CAUTION:

As a best practice for security reasons, confirm that URL obfuscation is enabled on systems that support applications that use the URL JSP tag. Additionally, if your application dynamically determines the parameters to the JSP tag through JavaScript code (and URL obfuscation is enabled), use the standard SafeURL JavaScript functions to obfuscate the URL. Click the Show JS Doc button to access the SafeURL documentation.

Complete syntax

In the syntax presentations below, replace any text in italics with your choice of value of that type.

<pega:url value=action-specification >
	<pega:option name="option1" />
	<pega:option name="option2" />
</pega:url>

The value attribute is required. The action-specification is either pyStream =myStream or pyActivity =myActivityClass.myActivityName.

Attribute Value

Attribute	Value
`value`	Text to be appended to the end of the system-generated URL as a Common Gateway Interface (CGI) percent-encoded string. In most cases, the URL identifies a stream rule name or an activity, in the format: `pyStreamName= myStreamName` or `pyActivity= myAppliesTo.myActivityName` Note: Using the URL JSP tag, you can start only activities with the May Start? box selected on the Security tab.

value

Text to be appended to the end of the system-generated URL as a Common Gateway Interface (CGI) percent-encoded string. In most cases, the URL identifies a stream rule name or an activity, in the format:

pyStreamName= myStreamName

pyActivity= myAppliesTo.myActivityName

Note: Using the URL JSP tag, you can start only activities with the May Start? box selected on the Security tab.

When using the URL JSP tag in a FORM tag, you can enter the action specification in either the FORM tag, the Submit button tag, or the anchor tag. If you have more than one action specification, enter it in the button tag or the anchor tag, rather than in the form tag.

<pega:url value= "pyStream=stream">
<pega:option name="option" />
</pega:url>

Enter the action-specification in the anchor or submit button.

<A HREF="<pega:url value=pyStream=myStream">
<pega:option name="primary" />
</pega:url>"
<B>MyAnchorText</B></A>

Options

This table lists each option and its corresponding property. Each option is explained in detail below. You can abbreviate the option using its first letter.

Option	Abbreviate as	Adds this parameter
`transid`	`t`	pzTransactionId
`frame`	`f`	pzFromFrame
`primary`	`p`	pzPrimaryPageName
`long`	`l`	Adds all three parameters

transid option — State synchronization

Used with a form and a Submit button, the transid option of the URL tag can be useful to maintain synchronization between the servers state and the user's browser state. Ideally, such synchronization works even when a user clicks the Back icon in the browser window.

The transid option causes the pzTransactionID parameter value to be included in the URL.

When the browser state changes as the result of a user submitting an HTML stream, the pzTransactionID parameter stores the server state as it corresponds to the current browser stream, tracking where the user has been and where the user is. In some situations, it is important that the browser state and the server state correspond accurately.

In situations where the server state data is not relevant, you can omit the transid option.

The transid option implies the frame option.

frame option — Target frame

Add the frame option to include the pzFromFrame parameter in the URL. Use this option if the target frame for the anchor is not the Standard frame, but is the current default frame. (The second parameter of the Show-HTML method determines the target frame for the HTML.)

The pzFromFrame property provides the default value for the pyTargetFrame parameter, the target frame used by the stream. If omitted, the system uses the Standard frame,

To add an explicit target frame, see below.

primary option — Called activity's primary page

Add the primary option to the URL tag to instruct the system to include the name of the current primary page as the value of the pzPrimaryPageName parameter in the URL when the user clicks an anchor or submit button. This may be used only if the current primary page is a top-level named page.

Use this option to tell the system to use the current primary page as the primary page when a user clicks the anchor. If the activity the anchor calls expects a primary page, use the primary option, or enter an explicit primary page using the pyPrimaryPageName parameter in your URL.

For example, an anchor that calls an activity to delete a page must indicate what page to delete. By contrast, an anchor that calls an activity that sets up its own primary page does not require such information.

long option — Include all options

To specify all three options, use the long option:

<A HREF="<pega:url "pyStream=myStream" >
	<option name="long" / >
</pega:url >"
<B>MyAnchorText</B></A>

Adding parameters and property-value pairs explicitly

You can append property-value pairs by property name to an anchor. To add property-value pairs, use an ampersand (&) character and enter the property value pair. Encode any special characters with the % character followed by two percent-encoded hexadecimal digits. (As a security measure, the value of activity parameters cannot contain certain characters including < and >.)

For example, you can cause an anchor to explicitly assign a primary page, using the pyPrimaryPageName parameter.

<A HREF="<pega:url value="pyActivity=myActivityClass.myActivity&pyPrimaryPageName=myPage" /> ">
<B>MyAnchorText</B></A>

For another example, you can add an explicit target frame using the pyTargetFrame parameter.

<A HREF="<pega:url
	value=MyStream=myStream&pyTargetFrame=myLeftFrame" />
<B>MyAnchorText</B></A>

The following query string parameters appear in many URL JSP tags:

Parameter or property	Description of value
pyActivity	Activity Name, second key part of an activity rule.
pzPrimaryPageName	Primary Page Name
pzFromFrame	HTML target frame
pzTransactionID	computed transaction ID, a hash code
pyStream	Second key part of an HTML rule.
Purpose	Second key part of a harness.

Setting property values

In an HTTP POST request, query string parameters with names that start with the two-character prefix $ are instructions to set property values on the clipboard.

...$PpyWorkPage$ppyLabel=Loan%20Underwriting...

This instructs Pega Platform to update the clipboard property pyWorkPage.pyLabel to the value "Loan Underwriting".

At runtime, Pega Platform checks each query string are against strict security criteria. To ensure the integrity of the system, clipboard updates are allowed only for properties that appear as an input field within the HTML FORM on the page. For example, a URL tag can includes the following legitimate property value setting:

...$PpyWorkPage$ppyWorkParty$gOriginator$ppyWorkPartyUri=smith%40myco.com..

If the property pyWorkPage.pyWorkParty(Originator).pyWorkPartyUri appears as an input field on the form, this query string sets the property value to "[email protected]". However, if the property value does not appear as an input value within the <FORM..> element, a security alert is logged:

The property value (if any) on the clipboard is not updated.
A security alert of type SECU001 (unexpected property) is added to the Alert log, with details in the Pega log.

The input field may be visible to the user, or in a hidden field within the <FORM tag>:

<input type="hidden" name="pyStatusWork" value="Resolved-Completed" />

An HTTP POST request string can also include a representation of an entire XML document that creates or updates an entire clipboard page. This feature is primarily used by internal processing facilities. This is not allowed from a web node. If a user on a web node attempts to send an entire XML document with HTTP POST, the clipboard updates do not occur and the system adds an SECU0002 alert to the Alert log.

Submit buttons

To use the URL tag with a Submit button, type the URL tag in the ACTION attribute of the Form tag like this:

<FORM action="<pega:url value="...">
	<pega:option name="long" />
</pega:url >

Reference the pyActivity or pyStream in the submit button.

<INPUT TYPE="Submit" NAME="pyActivity=Add">

When a user clicks the Submit button, the URL in the FORM tag is sent.

Always include the long option when the URL tag is used with the ACTION attribute of the FORM tag. Unlike stream processing with directives, stream processing with JSP tags does not automatically create hidden fields (<INPUT TYPE=HIDDEN..>) after a FORM tag.

Starting a new thread

Execution of the URL tag can start execution of a new Thread (clipboard user context) for the current requestor. Using the Property-Set method or Java, set the name of a new Thread as the value of the pxThread.pyThreadUse property before the URL tag executes. The default thread is named STANDARD; you can use any other alphabetic text for the new thread name.

JavaServer Page tags