Step 3: Specifying Pagelet Data Source Parameters

This section provides an overview of system variables supported as data source parameters, lists common elements, and discusses specifying pagelet data source parameters. This is step 3 in the Pagelet Wizard pagelet creation process. Specifically, this section discusses how to:

  • Specify activity guide data source parameter values.

  • Specify free text data source parameter values.

  • Specify HTML data source parameter values.

  • Specify IB connector data source parameters.

  • Specify Integration Broker data source parameters.

  • Specify navigation collection data source parameters.

  • Specify OBIEE data source parameters.

  • Specify pivot grid data source parameters.

  • Specify query data source parameters.

  • Specify rowset data source parameters.

  • Specify search record data source parameters.

  • Specify URL data source parameters.

  • Specify search record data source parameters.

When you set the Usage Type field to System Variable or User Specified on the Specify Data Source Parameters page, you can enter a system variable such as %UserId, which the system substitutes at runtime with the actual value represented by the variable. The following system variables are supported as data source parameters.

  • %AuthenticationToken

  • %ClientDate

  • %ClientTimeZone

  • %ContentID

  • %ContentType

  • %Copyright

  • %Currency

  • %Date

  • %DateTime

  • %DbName

  • %DbServerName

  • %DbType

  • %EmailAddress

  • %EmployeeId

  • %HPTabName

  • %IsMultiLanguageEnabled

  • %Language

  • %Language_Base

  • %LocalNode

  • %Market

  • %MaxMessageSize

  • %NavigatorHomePermissionList

  • %Node

  • %PasswordExpired

  • %Portal

  • %PrimaryPermissionList

  • %ProcessProfilePermissionList

  • %RowSecurityPermissionList

  • %RunningInPortal

  • %ServerTimeZone

  • %Time

  • %UserDescription

  • %UserId

Field or Control

Definition
Description

Displays a description of the data source parameter.

Usage Type

Select the type of end-user accessibility that you want to grant for the Data Source Parameter field when it appears on the pagelet. Options are:

  • Not Used: Select if it will not be used on the pagelet.

  • Fixed: Select to enter a fixed value for the data source parameter that the pagelet end user cannot modify.

  • System Variable: Select to assign a system variable as the data source parameter value. The value of the system variable is automatically inserted into the parameter when the pagelet appears. When you select this option, the pagelet end user cannot modify the data source parameter.

    For example, suppose that you specify %UserId as the system variable for a User data source parameter field. When the pagelet appears on a user’s homepage, the User field is populated by the %UserId system variable, which is the user ID used to access the pagelet.

  • User Specified: Select to enable end users to specify a data source parameter value for this field. When a pagelet contains a user-specified field, the Customize button appears on the pagelet title bar.

    End users can click this button to access a personalization page, where they can select a data source parameter value that they want to appear by default on the pagelet when they access it. They can select a value from a prompt, or they can manually enter their own value if no prompt values are available.

    If you change the usage type from or to User Specified for a data source parameter on a published homepage pagelet, you must unpublish and republish the pagelet.

  • Admin Specified: Enables users with administrative privileges to specify variables for this field as well as access the Configure link on the published pagelet and select from those parameters for users.

  • Context Sensitive: Enables users to specify context sensitivity for activity guide, OBIEE, and embedded pagelets.
Default Value

If you select User Specified or Admin Specified as the usage type and the data source parameter is a required value, you must enter the default value that should appear before a user enters a value. If the data source parameter is not a required value, you do not have to enter a default value.

If you select a default value when defining available user-specified values on the Specify Data Source Parameter Values page, this field is populated with that default value.

If you select User Specified as the usage type, you can enter a system variable as the default value. For example, to make the current date the default value for a user-specified parameter, enter a default value of %Date.

If you select System Variable as the usage type, you must enter the system variable to use as the data source parameter value.

See Understanding System Variables Supported as Data Source Parameters.

If you select Fixed as the usage type, you must enter the fixed value.

You can enter a value that includes the % and * wildcards at the beginning or end of a value in the Default Value field.

Magnifying glass icon

If you select Fixed as the usage type and the data source parameter has associated prompt values, you can use the Look up Value button to search for available data source parameter values.

If you select System Variable as the usage type, you can use the Look up Value button to access a list of valid system variables.

If you select User Specified as the usage type, this button does not appear.
User Values

If you select User Specified as the usage type, click to access the Specify Data Source Parameter Values page.

See Step 3: Specifying Pagelet Data Source Parameters.

Image: Specify Data Source Parameters (Activity Guide data source)

This example illustrates the fields and controls on the Specify Data Source Parameters for an activity guide data source when generating a pagelet for a specific activity guide instance. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters (Activity Guide data source)

When creating an activity guide pagelet, do one of the following:

  • If you are creating an activity guide pagelet for a specific activity guide instance, specify the template ID at step 2 and specify the instance ID on this page.

  • If you are creating an activity guide pagelet for an activity guide template with the instance ID to be supplied at run time, specify the template ID at step 2 and skip this page.

  • If you are creating a generic activity guide pagelet with both the template ID and instance ID to be supplied at run time, specify no template ID at step 2 and skip this page.

Data Source Parameters

Field or Control

Definition
.TEMPLATE_ID

Specified in step 2 when specifying the data source.
.INSTANCE_ID

Specify an instance ID only when you want to generate a pagelet for a specific activity guide instance.

When creating an free text data source pagelet, you skip step 3 and proceed to step 4, in which you select the pagelet display format.

When creating an HTML data source pagelet, you skip step 3 and proceed to step 4, in which you select the pagelet display format.

After selecting IB Connector as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters (IB Connector data source) (1 of 2)

This example illustrates a portion of the fields and controls on the Specify Data Source Parameters for an IB connector data source.

Specify Data Source Parameters page

Image: Specify Data Source Parameters (IB Connector data source) (2 of 2)

This example illustrates the remainder of the fields and controls on the Specify Data Source Parameters for an IB connector data source.

Personalization Instructions section

Define the data source parameters for the IB Connector data source. Click the User Values button to set the default values for users.

See Specifying User-Defined Data Source Parameters.

After selecting Integration Broker as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.).

Image: Specify Data Source Parameters (Integration Broker data source)

This example illustrates a portion of the fields and controls on the Specify Data Source Parameters for an Integration Broker data source.

Specify Data Source Parameters page

This step is applicable for the Integration Broker data source if the service operation is based on a structured message or if the message is structured but contains a schema. The structure that is associated with the message is translated into data source parameters on this page.

If the message is unstructured, then no schema structure has been associated with the message. Therefore, no data source parameters can be supplied and Pagelet Wizard bypasses this step.

You must supply values for all rows with the Required option selected.

Personalization Instructions

Use the Personalization Instructions text box . These personalization instructions appear on the Personalization page of the pagelet.

Note: Personalization instructions must be translatable.

After selecting Navigation Collection as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters (Navigation Collection data source)

This example illustrates the fields and controls on the Specify Data Source Parameters for a navigation collection data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

Data Source Parameters

Pagelet Wizard analyzes the selected navigation collection and retrieves a list of predefined parameters and any related prompt list values. You cannot add to the list of parameters.

Field or Control

Definition
Field Name

Displays the following data source parameters required by the navigation collection data source.

.INCLUDECHILDREN: Determines whether the pagelet displays navigation collection child links.

.MAXCHILDLINKS: If the pagelet is defined to display child links, determines the maximum number of navigation collection child links to display.
Required

This option is selected if the data source parameter must contain a value on the pagelet to retrieve data successfully. For example, the .INCLUDECHILDREN field is required.

If this option is selected and is display-only, the value is set in the application class at the API level.
Reset to Default

Click to reset the values on this page to the default values specified by the navigation collection data source API.
Values

Click the Values link to set the default values for users.

Personalization Instructions

Use the Personalization Instructions text box to enter instructional informs for the pagelet. These personalization instructions appear on the Personalization page of the pagelet.

Note: Personalization instructions must be translatable.

After selecting OBIEE Report as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters page (OBIEE Report data source)

This example illustrates the fields and controls on the Specify Data Source Parameters page for an OBIEE report data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

Data Source Parameters

Pagelet Wizard analyzes the selected OBIEE report and retrieves a list of predefined parameters and any related prompt list values. You cannot add to the list of parameters.

Field or Control

Definition
Field Name

Displays the data source parameters that correspond to the OBIEE prompts associated with the selected OBIEE report. This field also displays the required system-supplied .MAXROWS query data source parameter that you can use to limit the amount of data returned on the pagelet.
Description

This field contains a description that identifies the purpose or location of the OBIEE field.
Required

This option is selected if the data source parameter must have a value entered on the pagelet to retrieve data successfully. For example, the .MAXROWS field is required.

If this option is selected and is display-only, the value is set in the application class at the application programming interface (API) level.

If you leave this option deselected, the data source parameter value can be cleared at runtime, or it can be entered to refine the data selection criteria.
Reset to Default

Click to reset the values on this page to the default values specified by the OBIEE data source API.

After selecting Pivot Grid as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters page (Pivot Grid data source)

This example illustrates the fields and controls on the Specify Data Source Parameters page for a pivot grid data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

Data Source Parameter Details

Displays the Configure pivot grid views link, which you click to open the Pivot Grid Views Component page where you can define the pivot grid options.

See Specifying Display Options.

Data Source Parameters

Pagelet Wizard analyzes the selected pivot grid and generates the list of pagelet parameters shown in this step. You cannot add to the list of parameters.

Field or Control

Definition
Description

Enter text that describes the field.
Usage Type

Select the way the system uses the parameter. Select one of these options:

  • Admin Specified

  • Context Sensitive

  • Fixed

  • Not Used

  • System Variable

  • User Specified
Required

Select to require a value for the parameter.
Default Value

Enter the parameter value that the system uses by default.
Reset to Default

Click to set all values on this page to the default values specified by the pivot grid data source API.

Pivot Grid Views Component

Access the Pivot Grid Views page (Click the Configure pivot grid views link on the Specify Data Source Parameters page).

Image: Pivot Grid Views page

This example illustrates the fields and controls on the Pivot Grid Views page. You can find definitions for the fields and controls later on this page.

View Options section

Field or Control

Definition
View Name

Select the pivot grid view to use for this pagelet.
View Description

Enter text that describes the pivot grid view.
Display Options

Select which elements appear on the pagelet.

Choose one of these values:

  • Grid Only

  • Chart Only

  • Grid and Chart
Grid Options

  • Collapsible Data Area- select to enable the user to collapse the pivot grid into the grid header.

    If you select this option, the system automatically selects the Expanded State check box.

  • Expanded State - select to display the grid in the expanded state when the pagelet initially appears on the homepage or dashboard.

  • No Drag and Drop - select to disable the drag and drop functionality of elements within the pivot grid.
Chart Options

Enter or select values for the title, type, x and y-axis labels and x and y-axis angles (in degrees) of the chart.
Advanced Options

Enter values for the three-dimensional rotation angle (in degrees), height (in pixels), and width (in pixels) of the chart.
Save As

Click to open the Save View As dialog box, where you can either save the current pivot grid model as a new view or update an existing view.

After selecting PS Query as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters page (PeopleSoft Query data source)

This example illustrates the fields and controls on the Specify Data Source Parameters page for a PeopleSoft query data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

Data Source Parameters

Pagelet Wizard analyzes the selected query and translates the query prompts into the list of pagelet parameters shown in this step. You cannot add to the list of parameters. Most prompts will be marked as required; however, any prompts that are used exclusively in the IN clause of the query will not be marked as required.

Important! Query Prompts that are based on dynamic views should not be used as User Specified data source parameters. Unexpected results will occur.

You can attain advanced functionality with proper design of the query and the Pagelet Wizard pagelet. For example, you might want to create a pagelet that will show open purchase orders for a list of vendors, and allow each user to specify up to five vendors. To achieve this functionality, you would first create a query to retrieve the open purchase orders for up to five vendors. When you create this query, ensure that the five vendor ID prompts are used only in the IN clause of the query. You can then create a pagelet using the PS Query data type and choose the query that you have created. The five vendor ID prompts will be shown as data source parameters. However, they will be marked as not required. End users will then be able to specify any number of vendors (up to five) when they personalize the pagelet. Finally, update the personalization instructions on the pagelet to explain to the end users that they can supply up to five vendor IDs.

Field or Control

Definition
Field Name

Displays the data source parameters that correspond to the query prompts associated with the selected query. This field also displays the required system-supplied .MAXROWS query data source parameter that you can use to limit the amount of data returned on the pagelet.
Required

This option is selected if the data source parameter must have a value entered on the pagelet to retrieve data successfully. For example, the .MAXROWS field is required.

If this option is selected and display-only, the value is set in the application class at the application programming interface (API) level.

If you leave this option deselected, the data source parameter value can be cleared at runtime, or it can be entered to refine the data selection criteria.

Prompts tied to the IN clause of the query will not be marked as required.
Reset to Default

Click to reset the values on this page to the default values specified by the query data source API.
Values

Click the Values link to set the default values for users.

Personalization Instructions

Use the Personalization Instructions text box to enter custom personalization instructions for the pagelet. These personalization instructions appear on the Personalization page of the pagelet.

Note: Personalization instructions must be translatable.

When creating a rowset data source pagelet, you skip step 3 and proceed to step 4, in which you select your pagelet display format.

After selecting Search Record as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters (Search Record data source)

This example illustrates the fields and controls on the Specify Data Source Parameters for a search record data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

Data Source Parameters

Pagelet Wizard analyzes the selected search record and retrieves a list of search keys required for the search record. You cannot add to the list of data source parameters.

For fields that are search keys but that are not displayed on the search prompt page or in the result set for the search record (for example, the SETID and BUSINESS_UNIT fields), Pagelet Wizard assimilates the PeopleTools behavior and does not display the keys during design or at runtime. It simply binds in the same values that PeopleTools would use. These values are derived from the default field values established by the user in the PSRECDEFN table.

Field or Control

Definition
Field Name

Displays the data source parameters that correspond to the search keys required for the search record. This field also displays the required system-supplied .MAXROWS and SHOWRESULTS search record data source parameters.

Use the .MAXROWS field to limit the amount of data returned to the pagelet.

Use the SHOWRESULTS field to determine whether search results appear on the pagelet.

If this field value is set to Y, search record results appear directly on the pagelet with links to transaction data.

In addition, if this field value is set to Y, the search results grid displays results based on the supplied data source parameter default key field values. If no defaults are supplied, all results appear, up to the .MAXROWS value defined for the pagelet.

If this field value is set to N, the pagelet displays a search prompt for the selected search record. The Search By drop-down list box values that are available on the pagelet are the search keys for the search record.

If data source parameter default key field values have been defined, then when the pagelet is initially accessed, the default value appears in the begins with pagelet field.

Required

This option is selected if the data source parameter must have a value entered on the pagelet to retrieve data successfully. For example, the .MAXROWS and SHOWRESULTS fields are required.

If this option is selected and display-only, the value is set in the application class at the API level.

Search key values are not required because the search record pagelet supports partially populated keys so that you can define the pagelet to return all possible results.

If you leave this option deselected, the data source parameter value can be omitted at runtime, or the value can be provided to refine the data selection criteria.
Reset to Default

Click to reset the values on this page to the default values specified by the search record data source API.
Values

Click the Values link to set the default values for users.

Personalization Instructions

Use the Personalization Instructions text box to enter custom personalization instructions for the pagelet. These personalization instructions appear on the Personalization page of the pagelet.

Note: Personalization instructions must be translatable.

After selecting URL as the data type on the Select Data Source page, access the Specify Data Source Parameters page. (Select PeopleTools > Portal > Pagelet Wizard > Pagelet Wizard. On the Select Data Source page, click the Next button.)

Image: Specify Data Source Parameters page (URL data source)

This example illustrates the fields and controls on the Specify Data Source Parameters page for a URL data source. You can find definitions for the fields and controls later on this page.

Specify Data Source Parameters page

The data source parameters that you can define on this page correspond to URL query parameters, such as an HTTP GET request.

An HTTP GET request is a URL type for which parameters are placed on the query string separated by ? and &, such as http://search.yahoo.com/search?p=searchterm.

For example, the Yahoo! search page URL takes the form http://search.yahoo.com/search?p=searchterm. If you want to make searchterm a user-specified data parameter, enter a URL field value of http://search.yahoo.com/search in step 2 on the Select Data Source page. In step 3 on this page, add a data source parameter Field Name value of p and set its Usage Type field value to User Specified with a default value. Pagelet Wizard then adds the ?p=searchterm value, with the searchterm value able to be personalized by the user, to the URL before it retrieves the content to the pagelet.

You can specify a parameter for the number of milliseconds that a data source will wait for a response before timing out on the homepage. When you set .timeout_ms, you can then enter the number of milliseconds that the system will wait.

Passing Cookies

When the URL request is in the AuthenticationToken domain, then the URL data source will pass all cookies on the request to retrieve the content. (The only exception to this rule is if the request is being made back to the local web server. In that instance, only the PS_TOKEN cookie will be passed.) Any requests to servers outside of the AuthTokenDomain will not have any cookies passed.

To turn off the passing of cookies other than PS_TOKEN, add the parameter .passcookies as a Fixed usage type with a default value of False. Adding this parameter with a value of False will instruct pagelet wizard to pass only the PS_TOKEN cookie (and no other cookies) for requests within the AuthenticationToken domain. Adding the .passcookies parameter with a value of True is not recommended because this is the same as the default behavior.

Note: Make sure to examine any security impact that passing cookies might present in your configuration before setting this parameter.

Personalization Instructions

Use the Personalization Instructions text box to enter custom personalization instructions for the pagelet. These personalization instructions appear on the Personalization page of the pagelet.

Note: Personalization instructions must be translatable.

Click the User Values button on the Specify Data Source Parameters page to display the Specify Data Source Parameters Values page.

Image: Specify Data Source Parameter Values page

This example illustrates the fields and controls on the Specify Data Source Parameter Values page.

Specify Data Source Parameter Values page

Select the parameter value to be displayed to the user as the default value for the field. Users can select from this list of valid values when they personalize the pagelet.