url JavaServer Page tag

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
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 pyActivityName= myAppliesTo.myActivityName 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>

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

unclear 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. See Pega Developer Network article PRKB-10979 How to use the URL directive to configure HTML transactional forms for more information about the pzTransactionID token.

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. GENTG 7/22/09

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. GENTG 7/22/09

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>

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 >.) GRP-242

For example, you can cause an anchor to explicitly assign a primary page, using the pyPrimaryPageName parameter. COLEA 11/1/02

<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: PROJ-1295

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 rule.

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 Process Commander to update the clipboard property pyWorkPage.pyLabel to the value "Loan Underwriting".

At runtime, Process Commander 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. REALLY?

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.

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.

R-8914 03-04 MIRATBUG-3783 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. VAGUE

See the Pega Developer Network article PRKB-10979 How to use the URL directive to configure transactional HTML forms for more information on synchronizing user input with database transactions.