Understanding Search Records

You must correctly configure and select the search record for a component because the system uses the search record for several purposes:

  • The search record builds the search page for the component.

  • The search record builds the search query, which retrieves the component data and populates level 0 for every page in the component.

  • The search record builds the recent search results page for persistent searches.

  • The search record defines the service parameters that must be mapped for related content service definition of the PeopleSoft Component URL type.

When you click a content reference to access a component, the system examines the search record and dynamically builds the search page based on the search key, alternate search key, and list box item properties of the search record. If you designate fields as search keys or alternate search keys, then those fields appear on the search page. When the user enters values in the search fields and clicks the Search button, the system incorporates those values into the WHERE clause of the search query. If the values provided by the user uniquely identify one row of data, then the system proceeds directly to the main page with the available information. Otherwise, the query retrieves the rows that match the criteria and displays the rows in a list box at the bottom of the search page. If you define fields as list box items on the search record, the system displays those fields as columns grid in the result set.

You can use the %OPRCLAUSE meta-variable to filter the search results based on user profile settings for implementing row-level security. For more information on using this meta-variable see PeopleCode Language Reference: %OPRCLAUSE meta-SQL element.

This example shows elements of a search page:

This example illustrates the fields and controls on the Search page with search keys, alternate search keys, and list box items. You can find definitions for the fields and controls later on this page.

Search page with search keys, alternate search keys, and list box items

As soon as the system retrieves the search results, they appear as rows in the list box or grid. If recent search results caching is enabled, the system also temporarily stores this most recent (or persistent) search in the menu structure—in the navigation path and in the Recent Search Results menu under the Favorites drop-down menu.

When you select a row from the list box, the runtime system generates a second query to fill the level 0 row in the component. The runtime system examines the level 0 record for the component and checks its key fields. It tries to retrieve level 0 key field values from the fields in the list box and uses those values in the WHERE clause used to populate the level 0 record.

Note:

This process is the same whether you select the row from the initial search results list or from a persistent search.

The search record for a component might differ from the level 0 record definition for a component and might contain any number of search keys and list box items, but it must contain all of the key fields that are in the level 0 record for a component.

See Setting Record Field Use Properties.

Note:

When you add page items that are based on derived work records, do not select that record definition as the search record. Instead, select a record definition that stores the primary key or a SQL view that searches for the criteria that best enables users to identify the rows that they want to retrieve.

The search record might also contain logic to refine the search and limit rows of data. PeopleSoft applications implement data permission (or row-level) security in this way.

To configure menus in a PeopleSoft application, the easiest way to decide which search record to use is to look at the other search records that are used on the same menu. Look for pages with similar key structures and then evaluate the search records to see if any are suitable. You might want to print the PeopleTools Menu Listing cross-reference report (XRFMENU) to review which search records are used for pages and gain a better understanding of how search records are assigned in the application.