PeopleTools 8.52: PeopleSoft Search Technology

Creating Search Definitions

This section discusses:

Specifying general settings.
Mapping search attributes.
Managing search definition security.
Working with advanced settings.
Mapping components to search definitions.

Specifying General Settings

Access the General page, by selecting PeopleTools, Search Framework, Designer, Search Definition.

Search Definition

Displays the search definitions name as specified when adding a new value.

Note. At least one search definition must use the same name as the search category to which it belongs.

Description

Provide any additional information to distinguish the search definition.

Source Type	Select the type of query used to define the searchable data. Options are: Query or Connected Query.
Source Name	Select the name of the base Query or Connected Query.
Last Modified Date Time	Select the field specified in the query that determines the underlying record's update date and time. For example, LASTUPDDTTM.
URL Link	Select the query field containing the drilling URL defined for the query.
Title	Define the title of the search result document. This is the bold, first line of the search result. You can add text and bind variables to the title by clicking the *Title button. You cannot add text to the edit box directly.
Summary	Define the summary, or body, of the search result text. This is the text that appears below the title in a search result document. You can add text and bind variables to the summary by clicking the *Summary button. You cannot add text to the edit box directly.

Adding Text for the Title and Summary

In the Title\Summary dialog box you can insert custom text and bind variables, or a combination of the text and bind variables to accurately express the content of the search result document.

Insert Bind Variables

Click to launch the Insert Bind Variables dialog box and insert bind variables of the following types:

Query fields

Message catalog entries

System variables

Inserting Bind Variables into Title\Summary Text

When inserting bind variables into the title or summary text, you use the icon at the top left corner to open the Insert Bind Variables dialog box, enabling you to select the bind variable type and the specific bind variable. You can insert multiple bind variables and bind variable types within the title\summary text, as needed.

Query Fields

Use the Query Fields dropdown list to select the desired fields from the underlying query of the search definition.

Message Catalog

Specify the Message Set and Message Number to identify the specific message to display. To determine the text that displays use these options:

Message Catalog Text: Displays the Message Text edit box of the message catalog entry.

Message Catalog Explanation: Displays the Description edit box of the message catalog entry.

System Variables

Use the System Variables dropdown list to select the desired variable to display.

Mapping Search Attributes

Access the Map Search Attributes page, by selecting PeopleTools, Search Framework, Designer, Search Definition and selecting the Map Search Attributes tab.

The Map Search Attributes page displays all of the query fields of the query or connected query associated with the search definition.

Field to Index

Select the fields that you want to be indexed by the search engine. These fields would be those that you intend the end users would include in search queries intuitively. Fields that you do not select are not indexed. The remaining columns in the grid become enabled only after selecting the Field to Index check box for a particular row.

When selecting fields also consider fields that may help to group results or help distinguish security access.

Attribute Name

Displays the pre-defined attribute name that identifies the query field in the SES system.

Attribute Display Name

Determines how the attribute will display to the end user in the search results.

Note. The display name comes from the field labels associated with the Query Field Name. It cannot be entered manually. If the wording of the display name is not appropriate, you need to add a new field label. If you select a field that is not the default field label, the Attribute Name will change to reflect your choice.

Attachment Field

If the field contains an attachment URL, select this check box.

Is Faceted

Select to make this field a facet field, meaning that this field can be used to categorize and narrow down search results based on its value.

Defining a field as a facet requires some consideration. Facets cannot be blank, so if a field is not required, then the query needs to be structured so that there are not any blank values. You can use defaults on the record, or build COALESCE statements on a view to populate a field with a default (such as ‘None’, “NA” or “Blank”) if it contains a blank value.

Only string-type attributes can become facets. Number or date data types are not supported for facets.

Note. Currently, SES does not allow dates to be facets.

Note. Facets based on XLAT fields should be changed to use XLAT Long/Short in the query.

Note. SES has a data size limit of 2000 characters for faceted fields. The system truncates anything beyond 2000 characters.

Define Hierarchy

(Appears only for Connected Query.) Allows you to concatenate multiple fields into one SES attribute. If the attribute has hierarchical data, specify the hierarchy accordingly using the Define Hierarchy icon. When this icon is selected, you will see a Hierarchy Path subpage.

Hierarchy Path

(Appears only for Connected Query.) Displays the hierarchy path for a Connected Query, indicating where in the hierarchy of connected queries a particular query field resides. When defining a hierarchy, you start with the highest level (most general) field at the top and sequentially list more granular fields, with the most granular being at the bottom.

Note. This is mainly used for hierarchical facets. The label in the user interface is determined by the field on which the hierarchy is defined.

Example: Define Hierarchy Path

This is an example of defining a hierarchy path.

This definition is then displayed in the Hierarchy Path column of the Fields Included in the Index grid.

Managing Search Definition Security

Access the Security page by selecting PeopleTools, Search Framework, Designer, Search Definition and selecting the Security tab.

The Security page enables you to restrict access to search results generated by a search definition. Depending on the sensitivity of the search results, you can set these degrees of security:

No Security

Select to define no security restriction for a search definition's search results. Anyone with access to the application can view the search results for a search definition set to No Security. That is, the search results are public to all users.

Source Level Security

Select to allow or restrict access to the entire search definition as per the specified user or role. That is, only specified users and roles are able to view search results for that search definition.

Document Level Security

Select to restrict access to specific search results (documents) generated by a search definition. That is, with document level security, users can view search results generated by that search definition, but only the documents to which they have access.

Note. This is generally referred to as row-level security in PeopleSoft applications.

Setting Source Level Security

Access the source-level security settings by selecting the Source Level Security radio button.

Type

Select Role or User depending on the scope of your intended access restriction.

Selecting Role restricts access to a specific PeopleSoft role.

Selecting User restricts access to a specific PeopleSoft user.

Name

Select the user or role name.

Privilege

Define the access privilege or restriction.

Allow. The specified role or user is allowed to view search results for this search definition.

Deny. The specified role or user is not allowed to view search results for this search definition.

Note. Source-level security applies to every document within that search definition (SES data source).

Setting Document Level Security

Access the document-level security settings by selecting the Document Level Security radio button. Document-level security can also be thought of as attribute-based security.

With document-level security, one or more PeopleSoft Query columns act as the security attribute. You can then specify an application class (AppClass) that returns a list of values for the selected security attributes. When the user submits the search request, SES compiles a list of values returned from the application class associated with that specific user to build the security filter.

Document Level

Query Name

Select the name of the query or connected query containing the fields you want to use to restrict access.

Source Field

Select the field which will identify security values which will determine access.

The source field(s) selected becomes the security attribute having the specified privilege. At indexing time, when the crawler inserts application data into the index, the values populating the selected source field(s) will carry the specified privilege.

Privilege

Define the access privilege or restriction.

Allow. The value specified in the Source Field is allowed access to the data for this row in the search results.
Deny. The value specified in the Source field cannot see the data for this row in the search results.

Note. The privilege of Deny is useful in situations where there are too many values for the security attribute if Allow were selected. For example, rather than enabling access to nine out of ten field values, it is more efficient to deny access only to the one you want to restrict.

Note. If multiple attributes appear in the grid the system effectively inserts an AND clause between the items in the grid.

Document Filter App Class

The application class specified in the Document Filter App Class section creates a list of values for the security attribute at query time. The application class enables you to define and run additional filters and logic against the application data contained in the indexed source fields.

As needed, PeopleSoft applications will provide filtering App Classes for delivered search definitions. For any custom search definitions, or additional filtering requirements, you will need to create or modify the filtering App Classes.

Package Name	Select the name of the appropriate App Package.
Path	Select the path pointing to the App Class.
Class ID	Select the class ID for the App Class.

For example, assume you want to compile a list of valid SETIDs to which the user may have access. You define an application package that would contain a method called evaluateAttrValues. This passes the search definition name (sboName), the name of the security attribute field that was identified in the search definition, and the user who will access the data. The application method would then build a list of valid values for that user and return it to SES for comparison against the data to see if the attribute value on the data matches.

method evaluateAttrValues
   /+ &sboName as String, +/
   /+ &secAttr as String, +/
   /+ &srchUser as String +/
   /+ Returns Array of String +/
   /+ Extends/implements PTSF_SECURITY:SearchAuthnQueryFilter.evaluateAttrValues +/
   Local array of string &secValues;
   Local string &Role, &userPref, &csFullAccess, &csAdminAccess, &OnBehalfOf, 
   &docOwner, &BU_Security, &Security_Type, &SID_Security, &PermList;
   Local SQL &sqlRoles, &sqlUserPrefs, &sqlDocOwners;
   
   &secValues = CreateArrayRept("", 0);
   
      /*&BU_Security, &Security_Type, &SID_Security*/
      SQLExec("Select SETID_SECURITY, SECURITY_TYPE 
      from PS_INSTALLATION_FS ", &SID_Security, 
      &Security_Type);
      If &SID_Security = "N" Then
         &secValues.Push("A:ALL");
      Else
         Evaluate &Security_Type
         When "N"
            &secValues.Push("A:ALL");
         When "O"
            &secValues.Push("U:" | &srchUser);
         When "C"
            SQLExec("Select OPRCLASS from PSOPRDEFN where OPRID = :1", 
            &srchUser, &PermList);
            &secValues.Push("P:" | &PermList);
         End-Evaluate;
      End-If;
End-method;

Note. Concatenating multiple attribute values using a separator, you can achieve an OR clause between attributes. For example, in the this sample "A:ALL" and "U:"|&srchUser are two different attributes merged into a single attribute to achieve the OR clause.

Note. To achieve improved performance, the security attribute should be chosen in such a way that no more than 50 values are returned per user per attribute.

Working With Advanced Settings

Access the Advanced page by selecting PeopleTools, Search Framework, Designer, Search Definition and selecting the Advanced tab.

Define Query to Delete SBO

Query Name

Select the query that you’ve defined to remove orphaned search documents. This is your deletion query.

For example, for rows of data that have been deleted from the database, you would want to ensure that those rows of data (or search result documents) no longer appear in the search index.

Note. Even though this query is defined the same way as the source type query is defined, the difference is that the result of the query is used for deleting the already indexed documents from SES. The Drilling URL field acts as the primary identifier to locate the documents to be deleted. This means the drilling URL must be identical to the drilling URL built for the original query.

Delete SBO Query will not be executed during the first index build of a search definition. It only becomes active after the initial index is populated.

See Defining a Deletion Query.

URL Link Field

Select the drilling URL field for the query selected.

Pre Processing AE Library

Before an index build is run, data can be manipulated to perform additional tasks. For example, it may be required to search through subqueries to determine if one or more subquery might have changed and to update the last updated datetime value on the parent so that the change is recognized. Another use might be to calculate or summarize a value to be indexed. Another common case for pre processing occurs when a query is created based on staging tables. In this case the pre processing Application Engine program can be used to populate the staging tables. This is useful when the data cannot be retrieved using simple query (such as hierarchal or computed data).

You can define an Application Engine routine to perform these tasks.

Note. Pre and post processing adds to the overall indexing time, and it is recommended not to use this in scenarios where it can be avoided.

Note. Application Engine programs used for pre or post processing should be defined as type Library.

AE Library	To call additional processing logic from Application Engine, specify the correct AE Library (Application Engine program) to run.
AE Section	Specify the Application Engine program section to run.

Post Processing AE Library

After an index is built, certain clean-up functions might need to be performed, such as removing the records in your delete query, or cleaning up staging tables. Use the post processing Application Engine routine to perform these functions.

AE Library	To call additional processing logic from Application Engine, specify the correct AE Library (Application Engine program) to run.
AE Section	Specify the Application Engine program section to run.

Alternate Search Keywords

Alternate search keywords

Enter any alternate search keywords that users are likely to submit when running search requests. For example, rather than submitting the more official "purchase order" phrase, a user may be more likely to search on "PO" instead.

This field is translatable. If supporting multiple languages, the keywords need to be translated.

Mapping Components to Search Definitions

Access the Component Mapping page by selecting PeopleTools, Search Framework, Designer, Search Definition and selecting the Component Mapping tab. The Component Mapping page enables you to map a component to a specific search definition to enable SES integration with Search Pages.

Mapping a component to a search definition effectively assigns component level security to the search definition. For this reason, if the Search Definition is assigned to a component, document level security is turned on by default.

Note. Multiple components can be mapped to the same search definition. When a component is mapped, the security type is changed to document level security, and a user having access to any one of the components will be able to search inside the search index. The security type cannot be changed, but you can add more security attributes to extend the security.

Important! Search definitions mapped to a component must use document level security.

Market

Select the Market for the component.

Component Name

Select the component.

Search Criteria

Enter any additional custom search criteria to be added automatically to the SES search query during a Search Pages keyword search.

Note. The system appends additional search criteria as is to the search query. The Search Criteria field is “free text”. The Search Framework performs no validation or parsing during design time or run time.

Viewing Search Attributes

Access the Search Attributes page by selecting PeopleTools, Search Framework, Designer, View Search Attributes and selecting the Display Fields tab. Search attributes are used for creating aliases of the actual search query fields from PeopleSoft Query or Connected Query in the Oracle RSS feeds.

SES supports only three data types:

String
Number
Date

PeopleTools maps the PeopleSoft data types to SES data types. The Search Attributes page displays a search attributes mapped SES data type.

The search attributes page is read-only and provides a quick view of all attributes currently authorized for sending to SES. Every time a field is mapped in a Search Definition, the system adds an entry to this grid for the field. Because a field can exist on more than one search definition, it is not generally removed from this grid.

Search attributes are retained separately from a search definition and this enables:

Reusability. You can reuse the same search attributes amongst multiple search definitions.
Increased usability. Search attributes enable you to modify the attribute name or query field name from the end user, who will see the attribute display name. For example, adding the display value of "Employee ID" is more readable and understandable than displaying the field name EMPLID.
Quick Access. You can view and sort all search attributes in the system and check their datatypes without having to open SES or Application Designer.

Field to Index	Select the fields that you want to be indexed by the search engine. These fields would be those that you intend the end users would include in search queries intuitively. Fields that you do not select are not indexed. The remaining columns in the grid become enabled only after selecting the Field to Index check box for a particular row. When selecting fields also consider fields that may help to group results or help distinguish security access.
Attribute Name	Displays the pre-defined attribute name that identifies the query field in the SES system.
Attribute Display Name	Determines how the attribute will display to the end user in the search results. Note. The display name comes from the field labels associated with the Query Field Name. It cannot be entered manually. If the wording of the display name is not appropriate, you need to add a new field label. If you select a field that is not the default field label, the Attribute Name will change to reflect your choice.
Attachment Field	If the field contains an attachment URL, select this check box.
Is Faceted	Select to make this field a facet field, meaning that this field can be used to categorize and narrow down search results based on its value. Defining a field as a facet requires some consideration. Facets cannot be blank, so if a field is not required, then the query needs to be structured so that there are not any blank values. You can use defaults on the record, or build COALESCE statements on a view to populate a field with a default (such as ‘None’, “NA” or “Blank”) if it contains a blank value. Only string-type attributes can become facets. Number or date data types are not supported for facets. Note. Currently, SES does not allow dates to be facets. Note. Facets based on XLAT fields should be changed to use XLAT Long/Short in the query. Note. SES has a data size limit of 2000 characters for faceted fields. The system truncates anything beyond 2000 characters.
Define Hierarchy	(Appears only for Connected Query.) Allows you to concatenate multiple fields into one SES attribute. If the attribute has hierarchical data, specify the hierarchy accordingly using the Define Hierarchy icon. When this icon is selected, you will see a Hierarchy Path subpage.
Hierarchy Path	(Appears only for Connected Query.) Displays the hierarchy path for a Connected Query, indicating where in the hierarchy of connected queries a particular query field resides. When defining a hierarchy, you start with the highest level (most general) field at the top and sequentially list more granular fields, with the most granular being at the bottom. Note. This is mainly used for hierarchical facets. The label in the user interface is determined by the field on which the hierarchy is defined.