45.1 Introduction to Search

WebCenter Portal's search provides a unified, extensible framework that enables the discovery of information through an intuitive user interface. It honors application security settings by returning only the results a user is authorized to view. Users can save their searches for reuse, including searches with complex search refinement conditions.

WebCenter Portal provides two ways of searching your application:

Oracle Secure Enterprise Search (SES) adapter

Oracle WebCenter Portal live search adapters

In addition, the Documents service provides its own search engine for file searches. This saves time and increases the relevancy of results by narrowing the scope of a search to files.

45.1.1.2 Understanding Search with WebCenter Portal's Search Adapters

Although Oracle SES is the preferred search platform for best performance, you can manually override search with Oracle SES and have Framework applications search using WebCenter Portal's original search adapters. WebCenter Portal's search adapters span all enabled and searchable services, such as documents, tags, people, and pages.

45.1.1.3 Click Actions on Search Results

If no Resource Action Handling is specified in the Framework application, then the default action when a search result is clicked is to render the search result in a new browser window. Also, results from services that provide resource viewers, such as Documents, Discussions or Announcements, open in their resource viewers. For more information about resource viewers and the Resource Action Handling framework, see Section 7.3, "Extending Your Framework Application with Custom Components."

45.1.2 What Happens at Runtime

At run time, users can perform global (application-wide) searches from the Search task flow or from the Search toolbar and refine and save searches.

45.2.2 Setting up Connections for Oracle SES

You can create a connection to Oracle SES to search repositories outside WebCenter Portal and override using Oracle SES as the default search crawler with Fusion Middleware Control or WLST. This allows users to search other Framework application resources, such as people.

Set up a connection to Oracle SES. In the Application Navigator, expand Application Resources. Right-click the Connections node, select New Connection, and then Oracle Secure Enterprise Search.

Select to create the connection in either the Application Resources or IDE connections. A connection in Application Resources is available only for that application, while a connection in IDE connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE connections to avoid the need to re-create it.

Note:

If you create the connection in IDE, then the connection must be added to the application later. For example, in the Resource Palette under IDE connections, right-click the connection and select Add to Application.

Enter values for the fields in the dialog. For example:

For Connection Name, enter a meaningful name, for example, SESconnection. This name cannot be changed after it is created. (To use a different connection name, create a new connection.)

For SOAPURL, enter the URL for the Oracle SES Web Services endpoint, for example:

http://host:port/search/query/OracleSearch

Under Federation Trusted Entity, for Entity Name, enter the trusted entity defined for this application on the Oracle SES instance; for example, wcsearch.

A trusted entity allows the application to authenticate itself to Oracle SES and assert its users when making queries on Oracle SES. This trusted entity can be any user that either exists on the identity management server behind Oracle SES or is created internally in Oracle SES. You can find (or create) the trusted entity on the Global Settings - Federation Trusted Entities page of Oracle SES.

For Entity Password, enter the password of the Federation Trusted Entity user.

Under Application Configuration, select the box for Set as default connection for the Search service.

This ensures that your application uses that connection to access Oracle SES. The Search service uses only one Oracle SES connection.

Note:

After you create a connection as the default connection, you cannot edit it so that it is not the default. To use a different default connection, you must create a new connection and mark that as the default connection.

For Source Group, enter the Oracle SES source group in which to search. If a value is not provided, then all crawl sources in the Oracle SES instance are searched.

Note:

Source groups present a good way to segment your searchable data on Oracle SES. Given an Oracle SES instance that keeps a search index on all corporate data, you can use source groups to make only a portion of your corporate data available to WebCenter Portal's search. For more information on creating source groups, see Oracle SES Administrator's Guide.

Under Testing, for User name, enter the name of a user present in both the Oracle Identity Management server configured for your application and the Oracle Identity Management server configured for Oracle SES.

In the Application Navigator, right-click this application and select Run. It may take a few moments for the operation to complete.

Enter the user name and credentials that you created when you defined security.

Note:

To return results, the Search service requires that other WebCenter Portal services are included in the application.

45.2.3.3 How to Modify the Search Service Task Flow Parameters

With the Search service task flow parameters, you can customize the appearance and behavior of a task flow instance. For example, you can restrict search results to include only specific services, document types, and spaces, or you can change the size of the search box.

Table 45-3 describes the properties that are unique to the Search service task flows.

Table 45-3 Search Service Task Flow Parameters

Property

Description

Task Flow

customAttributes

List of custom attributes to show when displaying search results.

To include one or more custom attributes in the search results, set this to a list of custom attribute names, separated by commas. An optional label prefix may be provided with the custom attribute name to display instead of its associated custom attribute name. Use the format: label:name.

Search

Search Toolbar

hideRefiners

List of refiners to hide when displaying search results.

To hide one or more refiners, set this to a list of refiner names, separated by commas (choose from creator, date, space, content, and tags).

Search

Search Toolbar

keywordsInputRendered

Show or hide the input box.

Set to true (default) to show the input box, or set to false to hide it.

Search

mimeType

List of MIME types to limit the search.

To limit the search to certain document types, set this to the list of MIME types of the documents (such as PDF, PPT, DOC), separated by commas.

This also can be set to the Documents service with oracle.webcenter.doclib.

Note: To limit search to Microsoft Word documents and WebCenter Portal pages, set this parameter to application/msword, and set the serviceIds parameter to oracle.webcenter.doclib,oracle.webcenter.page.

List of unique IDs to limit the search scope. To limit the search to a list of spaces, set this to the list of GUIDs of the spaces, separated by commas.

For example: #{spaceContext.currentSpaceGUID} or s8bba98ff_4cbb_40b8_beee_296c916a23ed

Search

Search Toolbar

resourceScope

Unique ID to limit the search scope. To limit the search to a particular space, set this to the GUID of the space.

For example: #{spaceContext.currentSpaceGUID} or s8bba98ff_4cbb_40b8_beee_296c916a23ed

Note: This parameter has been deprecated. It is included for backward-compatibility only.

Search

searchBoxSize

Value to limit the size of the search box.

The default value is 42. Enter a lower number (for example, 30) to shorten the length of the search box. This also changes the size of the search box in the Search task flow.

Search Toolbar

serviceIds

List of IDs of services or executors to include when displaying search results.

To display only people profiles and documents in the Content Server, set this parameter to oracle.webcenter.peopleconnections.profile, oracle.webcenter.doclib. If nothing is specified, then all services are searched.

Note: This value is set automatically and is for internal use only. Do not change it unless you want coded search main views.

Search

scope

List of unique objects to limit the search scope.

Note: This parameter has been deprecated. Use the searchScope parameter instead. (If a value is set for this parameter, then any value in searchScope is ignored.)

Search Toolbar

Note:

The All Saved Searches and the Search Preferences task flows do not have any unique properties.

45.2.4 Setting Security for the Search Service

The Oracle SES adapter must be configured with an identity management system to validate and authenticate users. This is necessary for searches to return only results that the user is allowed to view based on access privileges. Because WebCenter Portal uses identity propagation when communicating with Oracle SES, WebCenter Portal's user base must match that in Oracle SES. One way this can happen is by configuring WebCenter Portal and Oracle SES to the same identity management system. For detailed information, see the section "Oracle SES - Configuration" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

WebCenter Portal's original search adapters rely on individual services to ensure that the user performing the search can view results. Search results are returned based on user privileges. When unauthenticated, queries return only public content. Only authenticated users of an ADF-secured Framework application can save searches.

ADF security is configured by default if you created your application using WebCenter Portal's Framework application template. For information about configuring ADF security, see Section 69.3, "Configuring ADF Security."

45.3 Advanced Information for the Search Service

This section describes optional features available with this service. It includes the following subsections:

In the Application Navigator, right-click the page and select Run. As long as the application has been ADF-secured, you should see a login page. It may take a few moments for the operation to complete.

If you configured ADF security, then enter the user name and password that you provided and click Submit.

Enter some search criteria in the field and click the Search icon. You may get few, if any, results if the application is not populated with much besides the Search service itself.

45.3.2 Adding the Search - Saved Searches Task Flow

You can add the Search - Saved Searches task flow to provide a simple launch pad for running saved searches within the application. To add this task flow to your Framework application, follow the instructions provided for the Search Toolbar task flow in Section 45.2.3, "Adding the Search Service at Design Time," but instead, drag and drop the Search - Saved Searches task flow onto the page.

The task flow renders links that, when clicked, run a saved search.

45.3.3 Adding the Search Preferences Task Flow

The Search Preferences task flow enables users to control which WebCenter Portal services are searched. By default, all enabled services are selected to be searched. Users can disable any service from which they do not want to see search results. Users also can select the order of services in their search results. For example, they may find that search results from the Documents service prove more useful that search results from other services.

45.3.5 Configuring Search with WebCenter Portal's Search Adapters

You can manually override search with Oracle SES and have Framework applications search using WebCenter Portal's original search adapters. WebCenter Portal's search adapters span all enabled and searchable services, such as documents, tags, people, and pages.

To enable search with WebCenter Portal's search adapters, edit the adf-config.xml file either to change all enable attributes in crawl-properties to false (Example 45-2) or to comment out the crawl-properties entirely (Example 45-3).

45.3.7 Using the Search Service REST APIs

WebCenter Portal provides REST APIs to support the Search service. Use the Search service REST APIs to post, read, update, and delete searches. You can specify keywords and the scope of the search; for example, the iPhone could search for "smith" in all spaces, documents and wiki pages. The API also lets you build a customized search user interface on top of the Search service.

This section describes the REST APIs associated with the Search service. It includes the following subsections:

45.3.7.1 Search Entry Point

Each REST service has a link element within the resource index that provides the entry point for that service. To find the entry point for the Search service, find the link element with a resourceType of:

urn:oracle:webcenter:search

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with the Search service.

45.3.7.2 Search Resource Type Taxonomy

When the client has identified the entry point, it then can navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Section 54.5.2.1, "Resource Type."

The taxonomy for the Search service is:

urn:oracle:webcenter:search
urn:oracle:webcenter:search:results

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the search resources support pagination (startIndex and itemsPerPage). Other query parameters are not supported (that is, search and projection).

45.3.7.4 Search Resource Types

45.3.7.4.1 urn:oracle:webcenter:search:results

Use this resource type to identify the URI to use to read (GET) a query containing keywords and attribute-specific criteria.

The request is represented by the URL and the response is a list of search results, each with metadata to help the end user choose an item to drill down, as well as cross links to the owning REST services, if available. If the owning REST service is unavailable, then an HREF link is provided.

The response XML can be paginated with standard URL parameters, and appropriate previous and next links provided along with a general template (with the query prepopulated) for the consuming application to do its own custom pagination.

Navigation Paths to results

This section shows how the client can navigate through the hypermedia to access this resource:

Optional: This narrows the search to one or more WebCenter Portal services, such as oracle.webcenter.doclib or oracle.webcenter.page. For example, setting this to oracle.webcenter.doclib searches only documents. If omitted, this searches all services.

Table 45-5 lists the resource types that the client can link to from this resource.

Table 45-5 Related Resource Types for search

rel

resourceType

self

45.3.8 Using the Search Service Data Control

Use the Search service data control to build a customized search user interface with a Framework application or a custom task flow. Deploying this task flow into an ADF library allows for a portable consumption of the task flow; for example, you could add it to a WebCenter Portal: Spaces application Resource Catalog to build site templates.

45.3.8.1 Search Data Control Methods, Attributes, and Classes

The Search data control contains the searchSes method. Table 45-6 describes its parameters for setting search refiners and limiting the scope of the search.

Table 45-6 searchSes Input Parameters

Parameter

Required?

Type

Description

scopeGuid

No

String

GUID value to filter results by spaces.

serviceId

No

String

The service ID of the item; for example, oracle.webcenter.doclib searches only documents. If omitted, this searches across all services.

keywords

Yes

String

Search terms.

predicates

No

List

Collection of predicates.

fetchRefiners

No

Boolean

Whether to fetch refiners. If omitted, the default value is false.

startIndex

Yes

Integer

Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.

45.3.9 Building Adapters for the Search Service

You can use search adapters to add other sources to your search results. WebCenter Portal framework automatically discovers these search adapters and consolidates them in formulating search results in your application. Subsequently, when you expose your custom component to the Search service in your application, it is included in the federated search.

This section describes how to extend WebCenter Portal's search through search adapters. It includes the following subsections:

45.3.9.1 How to Add a Search Source

To add a new search source, you must create Java classes for the new source to manage the incoming queries and return search results. After you add the necessary Java classes to your application, you must register them with the Search service.

When performing a search, the search framework calls QueryManager.createRowQueryHandler with a query object and a List<QName> that describes the columns sought. In return, the framework receives a QueryHandler<Row>.

A QueryHandler can be a QueryFederator or a QueryExecutor. A QueryFederator is just a collection of other QueryHandlers. With the QueryFederator, the framework can get a list of the child QueryHandlers and keep recursing until all QueryExecutors are found.

The framework calls the execute method on the QueryExecutor to get a QueryResult<Row>, which is an extension of java.util.Iterator<Row> that iterates and retrieves rows of results.

One possible implementation would be to create these classes:

SampleQueryManager ...

SampleRowQueryExecutor ...

SampleRowQueryResult ...

SampleRow ...

To add a new search source with a similar query manager:

In Oracle JDeveloper, open the application in which to add the search source.

Confirm that the WebCenter Common library is included in your project:

In the Application Navigator, right-click your project and select Project Properties and then Libraries and Classpath.

If the WebCenter Common library is not included, as shown in Figure 45-8, then click Add Library and select it.

45.3.9.2 How to Register a Custom Adapter

To register your query manager with the Search service, you must edit the service-definition.xml file. The SampleQueryManager line exposes the custom adapter's query manager implementation to the Search service so that the custom adapter is included with any search user interface.

45.3.9.3.1 Searchable Attributes

WebCenter Portal's search user interface exposes searches based on three fields: keywords, date, and person. Each service, in its own search implementation, honors these fields to the best of its capabilities. At minimum, it supports the keywords field. When you define your own search adapter, you must honor these fields to the best of your adapter's capabilities, as described in Section 45.3.9.3.8, "Selectable Attributes."

45.3.9.3.2 Keywords

By default, the keyword field is in oracle.webcenter.search.TextPredicate. The field can comprise multiple words, with the service determining how to interpret multiple words. The Search service does not tokenize before the call comes to the service, but here are some guidelines:

If two or more tokens are enclosed within quotes, then they should be interpreted as one word.

Unless the OR operator is explicitly set, it is assumed that the default conjunction among the words in the keywords field is AND.

45.3.9.3.3 Date Condition

For Search service to support filtering of query results by last modified date, the service implementation of the WPSAPI must support the use of oracle.webcenter.search.AttributePredicate, accessible from the query object, that uses oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED. The supported comparators must include the following:

oracle.webcenter.search.ComparatorConstants.GREATER_THAN

oracle.webcenter.search.ComparatorConstants.GREATER_THAN_OR_EQUALS

They may also include the following:

oracle.webcenter.search.ComparatorConstants.EQUALS

oracle.webcenter.search.ComparatorConstants.NOT_EQUALS

oracle.webcenter.search.ComparatorConstants.LESS_THAN

oracle.webcenter.search.ComparatorConstants.LESS_THAN_OR_EQUALS

The literals for comparison should be of type java.util.Calendar.

45.3.9.3.4 Complex Date Condition

You can use the BETWEEN clause for dates. The complex date condition, instead of being a simple AttributePredicate, is a ComplexPredicate that contains one GREATER_THANAttributePredicate and one LESS_THANAttributePredicate with an AND conjunction operator. This ComplexPredicate must apply the AND operator with the rest of the fields (that is, keywords and person).

To differentiate between this case and the default case, service authors must check on the type of the predicate that is meant for the date condition. If it is an AttributePredicate, then it is the default case. If it is a ComplexPredicate, then it is a special case.

45.3.9.3.5 Person Condition

For Search to support filtering of query results by person, the service implementation of the WPSAPI must support oracle.webcenter.search.AttributePredicate, accessible from the query object, that uses oracle.webcenter.search.AttributeConstants.WPSAPI_MODIFIER.

The comparators supported must include the following:

oracle.webcenter.search.ComparatorConstants.EQUALS

oracle.webcenter.search.ComparatorConstants.CONTAINS

oracle.webcenter.search.ComparatorConstants.STARTS_WITH

oracle.webcenter.search.ComparatorConstants.ENDS_WITH

The literals for comparison should be of type java.lang.String.

45.3.9.3.6 Complex Person Condition

Service authors must check on the type of predicate that is meant for the person condition. An AttributePredicate is the default case.

45.3.9.3.7 Access

The Search service (as a caller) expects that the query's getPredicate() method likely returns an oracle.webcenter.search.ComplexPredicate that joins an oracle.webcenter.search.TextPredicate holding the keyword, and an oracle.webcenter.search.ComplexPredicate holding the date condition, and an oracle.webcenter.search.AttributePredicate holding the person condition.

45.3.9.3.8 Selectable Attributes

The following selectable attributes/columns should be supported by your search adapter in its search implementation:

Title (Required)

For each resource returned, the Search service user interface can display the title column, if provided. It is strongly recommended that the title column comes with the QName AttributeConstants.DCMI_TITLE.

Resource ID (Required)

For resources to communicate a unique identifier that allows the Search service to render a link to navigate to the resource view (or any declared views) of the service, the column with the name oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER must be returned as a column accessible from a row within the QueryResult<Row>.

The Search service extracts the DCMI_IDENTIFIER column and feeds it into the resource viewer as the value of the resourceId parameter when the link is clicked.

If your resource view (or any declared views) requires multiple columns in the primary key, then try to bundle all of them into a composite string value for the oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER column. The Search service treats that opaquely and passes it to your resource view, within which it may deconstruct the string into the various parts of the primary key.

Resource Type

For each resource returned, the Search service user interface can display the type column, if provided. The type column comes with the QName AttributeConstants.DCMI_TYPE. If the DCMI_TYPE column is not found, then the value of the DCMI_FORMAT column is used in its place. In your resource viewer, you can make use of the resource type to aid in the rendering of a resource.

Resource URL (in place of Resource ID)

In the absence of an oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER column, WebCenter Portal's Search service constructs the link from the value of the column specified by oracle.webcenter.search.AttributeConstants.DCMI_URI. With absolute URLs, the DCMI_URI can launch a link from the search results to the URL.

This allows for services, such as the Documents service and the Page service, to invoke the browser plug-in to render various results link targets, instead of invoking a resource view.

Last Modified Date

For each resource returned, the Search service user interface can display the last modified date column, if provided. To mirror the searchable attribute of the last modified date, it is important that users can see the last modified date as a returned column in the search result.

For most users, the last modified date is more relevant than the creation date. To have better consistency between the searchable attributes and the selectable attributes (so that users know what date to search with after seeing some values in the columns), it is strongly recommended that service authors return AttributeConstants.DCMI_MODIFIED rather than AttributeConstants.DCMI_CREATED. The last modified date is of type java.util.Calendar.

Creator

For each resource returned, the Search service user interface can display the creator and last modified by column, if provided. The search user interface combines them in the same column as a list of contributors for the found resource. The QNames to use are AttributeConstants.DCMI_CREATOR and AttributeConstants.WPSAPI_MODIFIED, respectively. The creator is of type java.lang.String.

Icon

For each resource returned, the Search service user interface can display the icon column, if provided. The icon column comes with the QName AttributeConstants.WPSAPI_ICON_PATH and corresponds to a valid path to an icon file that is accessible in the class path. The icon path is of type java.lang.String.

Size

For each resource returned, the Search service user interface can display the size column, if provided. The size column comes with the QName AttributeConstants.DCMI_EXTENT and corresponds to the size of the resource found. The size is of type java.lang.Number.

45.3.9.4 What Happens at Runtime

When you perform a search from the main view or toolbar, it should seamlessly include your new search source. For testing purposes, be sure to enter criteria that yields a result in your newly-added search source.

You can develop a custom search user interface in a Framework application without WebCenter Portal's Search service API, but still with Oracle SES as the application's search engine by using the Oracle SES Web Service Query API to do search functions. Also, action handling for search results can be managed with WebCenter Portal's Resource Action Handling framework, so that when an application resource (for example, a document) is clicked in the search results, the resource is shown in the viewer of the resource (for example, the Documents resource viewer). Moreover, if the application uses WebCenter Portal Navigation, then certain resource types can be shown in the navigation node of the resource.

This section describes the required steps to enable Resource Action Handling for handling search result action.

Use the Document Service Manager provided by WebCenter Portal to crawl documents.

The Document Services Manager creates an attribute called wc_url in the Oracle SES index for each document. The value of the wc_url attribute is a URL that goes to the Resource Action Handling module of the application. The URL uses the value of the WebCenter URL Prefix parameter in the Document Service instance as the prefix.

Set the parameter value as the host and port where the application is deployed, plus the context root; for example:

http://myhost:8888/DocumentsServer

Use the wc_url attribute for action handling in the search UI.

Typically, the search UI uses the URL attribute for action handling. To use Resource Action Handling for action handling of search results of the Documents resource type, use the wc_url attribute. Note that only search results with the Documents resource type have the wc_url attribute. Therefore, this must be done conditionally in the search UI code.

When a search result is clicked, the resource is rendered in the resource viewer of the resource, if available. The current search results page is over-written. Use Resource Action Framework to change this behavior.

Update the adf-config.xml file of the application to specify the Resource Action Handling class to use.

Example 45-10 shows how to use PopUpResourceActionViewHandler to show the resource in a popup window when a search result is clicked.

45.3.11 Troubleshooting the Search Service

This section describes common problems and solutions for the Search service.

Problem

There is a set timeout for querying each service. If a particular service does not return search results in the allotted time, then it times out. The Announcements and Discussions services are susceptible to timeouts. (In WebCenter Portal: Spaces, pages and spaces could have timeouts from search execution.)

Solution

To improve performance at design time, you can increase the values (in milliseconds) of timeoutMs and prepare TimeoutMs in adf-config.xml. The following is the relevant fragment of adf-config.xml, found in the Application Resources panel in the ADF META-INF folder:

<execution-properties timeoutMs="3000"prepare TimeoutMs="1000"/>

At runtime, you can configure timeouts using WLST or Fusion Middleware Control.

Scripting on this page enhances content navigation, but does not change the content in any way.