Using Search Records
This section provides overviews of search records and search records and persistent search results, and discusses how to:
Create search records.
Override 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 metavariable to filter the search results based on user profile settings for implementing row-level security. For more information on using this metavariable see %OPRCLAUSE.
This example shows elements of a search page:
Image: Search page with search keys, alternate search keys, and list box items
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.
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.
When you perform a component search, the results of your most recent search are temporarily stored—they persist—in the portal drop-down menu structure. The system stores the most recent component search results for the currently active component in the navigation path (breadcrumbs). Here is an example of the search results icon in the navigation path:
Image: Search icon at the far right in the navigation path
This example illustrates the fields and controls on the Search icon at the far right in the navigation path. You can find definitions for the fields and controls later on this page.
The most recent search for each of the five most recently visited components appear in the Recent Search Results menu:
Image: Recent Search Results menu showing two recent component searches
This example illustrates the fields and controls on the Recent Search Results menu showing two recent component searches. You can find definitions for the fields and controls later on this page.
Note: Components that do not generate search pages do not generate search results and, therefore, do not appear in the Recent Search Results menu or the navigation path.
When you access a recent search either from the navigation path or the recent search menu, the system displays the results in a grid on a modal pop-up page, which hovers over the currently active page.
Here you see the Recent Search Results pop-up page for the Tree Manager component:
Image: Tree Manager Recent Search Results pop-up page showing results grid
This example illustrates the fields and controls on the Tree Manager Recent Search Results pop-up page showing results grid. You can find definitions for the fields and controls later on this page.
Important! You must enable recent search results caching at the system level. The default setting for recent search results caching is disabled.
Recent Search Results Process
A persistent search enables you to circumvent the first part of the component search process by temporarily storing all search keys, which the system uses in the WHERE clause of the second part of the search process, in the menu structure. When you access a recent search and select an item from the list, the second query is generated and populates the component buffer.
Although the search process remains the same, the appearance of the search results page differs from component search pages.
Note these points about the search results page:
It is modal; it hovers over the transaction page, which is inactive until you dismiss the modal page or select a list item.
It is compact; it displays a maximum of five of the temporarily stored fields in the results grid.
It is moveable, which enables you to view the current transaction and see the search results simultaneously.
It displays an active link, a link that you can click to retrieve a specific row of data, in only the first column; all other columns are inactive.
It is configurable.
See Configuring Search Results Grid Columns in Persistent Searches.
Note these points about the accessibility and availability of persistent search results:
The most recent transaction search results for the currently active component appear in the navigation path next to the content reference name; a search icon is the visual indicator.
The one most recent search for each of the five most recently viewed components appears in the Favorites, Recent Search Results menu. The results appear by component name, for example, User Profiles.
The navigation path retains the most recent transaction search results until another search is performed.
Note: If you leave a component and return to it without having performed another search, the most recent search results reappear.
Any persistent search remains in the portal menu structures only until your PeopleSoft session expires, you sign out, or you close the browser.
Recent Search Results Page Construction
The standard, default Recent Search Results page uses these criteria to determine the fields that appear on the page:
Fields marked as search key fields appear in the results grid in the order in which they are listed in the record definition.
If the search record contains more than five search key fields, the other search key fields, while stored in the menu structure and accessible by the search process, are hidden from view.
If the search record contains fewer than five search keys, the fields marked as list box items appear in the grid in the order that they are listed in the record definition until the column limit of five is reached.
You can override which columns appear on the recent results search page by using the Persist in Menu property of the search record.
To create a search record:
Create the record definition and add the fields.
Select the key fields, search key fields, and list box items.
If the record is a view, write the SQL statement in the SQL editor.
See Using the SQL Editor.
Save and build the record definition.
You might want to reuse a component, changing only its search record.
You can accomplish this by overriding the component search record at the time that the component is invoked from a menu. To override a component search record, specify a different search record in the properties of the menu item that invokes the component. The component uses the override search record when it is invoked from that specific menu item; the search record set in the component properties remains unchanged.
By reusing components in this way, you can limit redundancy, keeping your application smaller and easier to maintain.