45 Integrating Search

This chapter describes how to integrate search at design time.

This chapter includes the following topics:

For more information about managing and including search, see:

45.1 Introduction to Search

WebCenter Portal 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.

WebCenter Portal provides two ways of searching your application:

  • Oracle Secure Enterprise Search (SES) adapter

  • Oracle WebCenter Portal live (delegated) search

Oracle SES is set as the default and preferred search platform. In addition to providing better scalability and performance than WebCenter Portal's live search, Oracle SES is beneficial for the following reasons:

  • Oracle SES provides unified ranking results, with the most relevant items appearing first.

  • Oracle SES provides more thorough search. For example, when searching lists, WebCenter Portal live search only searches list names and descriptions, while Oracle SES also searches list column names and column contents.

  • Oracle SES allows search of repositories outside of WebCenter Portal. Oracle SES results appear in the same result set as WebCenter Portal's search results.

  • Oracle SES supports the search REST APIs and data control for customizing your search interface.

In addition to the Oracle SES or live search functionality, the Documents tool 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 Understanding Search

Search with Oracle SES requires additional configuration in Oracle SES Administration, Oracle WebCenter Content: Content Server, and Oracle WebCenter Portal's Discussion Server.

Oracle strongly recommends using Oracle SES release 11.2.2.2 (included with WebCenter Portal release 11.1.1.8).

Note:

This chapter describes how to integrate Oracle SES release 11.2.2.2 in Portal Framework applications. If you choose to use Oracle SES release 11.1.2 or 11.1.2.2 instead, then see:

http://docs.oracle.com/cd/E28280_01/webcenter.1111/e10148/jpsdg_search.htm#BABBDFDC

This section contains the following topics:

45.1.1.1 Understanding Search with WebCenter Portal Live Search

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

45.1.1.2 Understanding Search with the Oracle SES Adapter

Oracle SES provides unified ranking results for the following resources:

  • Documents, including wikis and blogs

  • Announcements and discussions

Note:

WebCenter Portal applications include the Oracle SES crawler that indexes portals, lists, page metadata, and people resources. This crawler is not supported in Portal Framework applications.

Your search environment varies depending on the version of Oracle SES configured. For example:

  • If your system is configured with Oracle SES 11.2.2.2, then you can customize search on the Tools and Services - Search administration page. Oracle SES 11.2.2.2 supports faceted search, filtered search in the search box, and document thumbnails, while earlier releases of Oracle SES and implementations with live (delegated) search do not. (All customization with Oracle SES 11.2.2.2 is done on the Tools and Services - Search administration page, even though task flow parameters may display.)

  • If your system is configured with Oracle SES 11.1.2.*, then you can customize search using Search - Non-Faceted Search task flow parameters. Oracle SES 11.1.2.* supports saving searches and setting user preferences with search, while the 11.2.2.2 adapter and implementations with live (delegated) search do not.

Note:

Facets let users navigate indexed data without running a new search. Some search terms can provide massive results, but faceted navigation within search lets users clarify exactly what they are looking for, or even discover something new. Facets count the full corpus and have better response time that the search refiners used in earlier releases.

The Tools and Services - Search administration page shows what search is configured.

45.1.1.3 Click Actions on Search Results

If no Resource Action Handling is specified in the 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 components 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 4.3, "Customizing How Services Render Resources."

45.1.2 What Happens at Runtime

At runtime, users can perform global (application-wide) searches.

For more information about WebCenter Portal's search at runtime, see the "Searching for Information" chapter in Oracle Fusion Middleware Using Oracle WebCenter Portal.

45.2 Basic Configuration for Search

This section provides the steps for adding search to your application. It includes the following topics:

45.2.1 Configuration Roadmap - Oracle SES

Use the roadmap in this section as a guide through the configuration process.

Note:

If you override search with Oracle SES to use the original WebCenter Portal live search adapters, then no Oracle SES configuration is required. Skip ahead to section Section 45.2.3, "Adding Search at Design Time."

Figure 45-1 and Table 45-1 provide an overview of the prerequisites and tasks required to get Oracle SES working in Portal Framework applications.

Figure 45-1 Configuring Oracle SES for Portal Framework Applications

Description of Figure 45-1 follows Install WebCenter Portal: Framework and Oracle SES Configure Oracle SES with an identity management system Set up a Document Service Manager in Oracle SES Create a Federation Trusted Entity Create two crawl sources: Documents Crawler and Discussions Crawler Create a source group for the crawl sources Create facets and sorting attributes Configure a connection to Oracle SES in JDeveloper Add a Search service task flow to a page in JDeveloper Deploy using JDeveloper Deploy the application Deploy using WLST Deploy using WLS Admin Console (Optional) Secure the connection to Oracle SES with SSL Configure additional search parameters
Description of "Figure 45-1 Configuring Oracle SES for Portal Framework Applications"

Table 45-1 Configuring Oracle SES for Portal Framework Applications

Actor Task Sub-task

Administrator

1. Install WebCenter Portal and Oracle SES 11.2.2.2

 
 

2. Configure Oracle SES with an identity management system

 
 

3. Set up a Document Service Manager in Oracle SES

 
 

4. Create a Federation Trusted Entity using one of the following tools:

  • Oracle SES Admin Tool

  • WLST

 
 

5. Create two crawl sources: Documents Crawler and Discussions Crawler using one of the following tools:

  • Oracle SES Admin Tool

  • WLST

 
 

6. Create a source group for the crawl sources using one of the following tools:

  • Oracle SES Admin Tool

  • WLST

 
 

7. Create facets and sorting attributes

 

Developer

8. Integrate search in your application

8.a Configure a connection to Oracle SES in JDeveloper

Note: This step must include running the setSESVersion WLST command to enable the Tools and Services - Search administration page.

   

8.b Add a Search task flow to a page in JDeveloper

Developer or Administrator

9. Deploy the application using one of the following tools:

 

Administrator

10. (Optional) Secure the connection to Oracle SES with SSL

 

Administrator

11. Configure additional search parameters using one of the following tools:

  • Fusion Middleware Control

  • WLST

  • WLS Admin Console

 

45.2.2 Setting up Connections for Oracle SES

To search with Oracle SES, you must add the Oracle SES connection in the application. For more information, see Section 45.3.1, "Configuring Search with the Oracle SES Adapter."

  1. Add the search toolbar to a page, following Section 45.2.3, "Adding Search at Design Time."

  2. 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 SES Connection.

    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:

    1. 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.)

    2. For SOAP URL, enter the URL for the Oracle SES Web Services endpoint, for example:

      http://host:port/search/query/OracleSearch
      
    3. 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.

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

    5. 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. Search 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.

    6. 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.

    7. 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.

      You should see something similar to Figure 45-2.

    8. Figure 45-2 Create Oracle SES Connection Dialog

      Description of Figure 45-2 follows
      Description of "Figure 45-2 Create Oracle SES Connection Dialog"

    Click Test Connection and check the status.

    If the connection is successful, then click OK.

    After you have included the Oracle SES connection in your application, you should see it in your Application Resources panel, as shown in Figure 45-3.

    Figure 45-3 Oracle SES Connection in Application Resources

    Description of Figure 45-3 follows
    Description of "Figure 45-3 Oracle SES Connection in Application Resources"

    The Oracle SES connection is now included in the connections.xml file and is the default connection in the adf-config.xml file, as shown in Example 45-1.

    Example 45-1 Oracle SES Connection in adf-config.xml

    <ses-properties>
      <connection>SESconnection</connection>
      <data-group>MySources</data-group>
    </ses-properties>
    
  3. You must run the setSESVersion WLST command to obtain and store version information for the Oracle SES instance associated with your default connection. This enables the Tools and Services - Search administration page, which is necessary for customizing search settings with Oracle SES 11.2.2.2.

    To confirm that the Oracle SES version is set correctly, run the listSESVersion WLST command.

    For command syntax and examples, see the "setSESVersion" and "listSESVersion" sections in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

After your application has been deployed to an Oracle WebLogic managed server, you can configure it using WLST or Fusion Middleware Control. For more information, see Oracle Fusion Middleware Administering Oracle WebCenter Portal.

45.2.3 Adding Search at Design Time

This section describes the search task flows and explains how to integrate search into your application. It includes the following topics:

45.2.3.1 Search Task Flows

Table 45-2 lists the search task flows included with Oracle SES 11.2.2.2.

Table 45-2 Search Task Flows

Task Flow Definition

Search - Faceted Search

This task flow provides a rich search experience supporting faceted search, filtered search in the search box, and document thumbnails.

Note: This Search task flow is provided in environments where Oracle SES 11.2.2.2 is configured.

Search - Administration

This task flow allows access to the Tools and Services - Search administration page for customizing search settings.

Search - Toolbar

This task flow enables users to enter simple search criteria and run the search from the application. Search results are rendered as links.


Note:

The other Search task flows that display are not supported with the Search-Faceted Search task flow.

45.2.3.2 How to Add Search to Your Page

The Search - Toolbar task flow offers the easiest way to add search to your application. To add the Search - Toolbar task flow to your application:

  1. Follow the steps described in Chapter 2, "Setting Up Your Development Environment" to create a customizable page in your application.

    Note:

    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 74.3, "Configuring ADF Security."

  2. Open the page on which to add search.

  3. In the Resource Palette, expand My Catalogs, WebCenter Portal - Services Catalog, and Task Flows.

  4. Drag and drop the Search - Toolbar task flow onto the page.

  5. When prompted, select Region as the way to create the task flow.

    If a prompt to confirm the ADF library appears, click Add Library.

  6. Run your page with the search toolbar on it.

    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.

  7. The Search-Faceted Search task flow requires the Search - Administration task flow for access to the Search administration page (for customizing search settings). Add this task flow the same way you added the Search - Toolbar task flow.

Notes:

The Resource Palette also shows the Search - Saved Searches and the Search - Preferences task flows. These task flows are not supported with the Search-Faceted Search task flow.

To return results, search requires that other WebCenter Portal tools and services are included in the application.

45.2.3.3 How to Customize Search

In previous releases configured with Oracle SES, application specialists could customize search (that is, alter the layout of search results as well as search behavior) using the Search (Search - Non-Faceted Search) task flow parameters. With these parameters, they could narrow the scope of searches to specific portals, tools/services, and document types. Also, they could add custom attributes to the list of standard attributes returned with each search result item, and they could hide standard refiners available to users with search results.

With WebCenter Portal release 11.1.1.8 and Oracle SES 11.2.2.2, search is customized completely on the Tools and Services - Search administration page (instead of using task flow parameters). This is a much easier way to configure search. This new search experience makes use of faceted search. This new Search - Faceted Search task flow is used only if Oracle SES 11.2.2.2 is configured.

45.2.4 Setting Security for Search

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 "Oracle SES - Configuration" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

Note:

WebCenter Portal's live (delegated) search relies on individual tools and 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 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 74.3, "Configuring ADF Security."

45.3 Advanced Information for Search

This section describes optional features available with search. It includes the following topics:

Note:

The search REST APIs and data controls are available only for search using Oracle SES. They are not supported with search using WebCenter Portal's live (federated) search.

45.3.1 Configuring Search with the Oracle SES Adapter

WebCenter Portal applications automatically set Oracle SES as the default search adapter, but additional configuration is required in Oracle SES, Oracle WebCenter Content: Content Server, and Oracle WebCenter Portal's Discussion Server. See the "Managing Oracle Secure Enterprise Search in WebCenter Portal" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal for detailed information about the steps to set up search with the Oracle SES adapter.

After you have completed all configuration steps, validate the inclusion of Oracle SES results in WebCenter Portal's search.

  1. In the Application Navigator, right-click the page you created with the Search - Toolbar, and click 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.

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

  3. Click Submit.

    When the page loads, you should see your search toolbar.

    Figure 45-4 shows a sample results page for the search term webcenter, before Oracle SES has crawled anything.

    Figure 45-4 Search Results

    Description of Figure 45-4 follows
    Description of "Figure 45-4 Search Results"

    Figure 45-5 shows a sample results page after Oracle SES has been configured and crawled.

    Figure 45-5 Global Search Results

    Description of Figure 45-5 follows
    Description of "Figure 45-5 Global Search Results"

See Also:

Oracle SES documentation provided on the Oracle Fusion Middleware documentation library (in WebCenter Portal's product area)

45.3.2 Configuring Search with WebCenter Portal's Live Search

You can manually override search with Oracle SES and have applications search using WebCenter Portal's live (delegated) search.

To enable search with WebCenter Portal's live search, 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).

Example 45-2 Crawl Properties in adf-config.xml Set to False

  <searchC:adf-search-config
xmlns="http://xmlns.oracle.com/webcenter/search/config">
    <display-properties>
      <common numSavedSearches="5"/>
      <region-specific>
        <usage id="simpleSearchResultUIMetadata" numServiceRows="5"/>
        <usage id="searchResultUIMetadata" numServiceRows="5"/>
        <usage id="localToolbarRegion" numServiceRows="5"/>
      </region-specific>
    </display-properties>
    <execution-properties timeoutMs="7000" prepareTimeoutMs="3000"/>
    <crawl-properties fullCrawlInterval="P5D" enableWcServicesCrawl="false"
                      enableWcDiscussionsCrawl="false" enableWcUcmCrawl="false"/>
    <ses-properties>
      <connection/>
      <data-group/>
    </ses-properties>
  </searchC:adf-search-config> 

Example 45-3 Crawl Properties in adf-config.xml Commented Out

  <searchC:adf-search-config
xmlns="http://xmlns.oracle.com/webcenter/search/config">
    <display-properties>
      <common numSavedSearches="5"/>
      <region-specific>
        <usage id="simpleSearchResultUIMetadata" numServiceRows="5"/>
        <usage id="searchResultUIMetadata" numServiceRows="5"/>
        <usage id="localToolbarRegion" numServiceRows="5"/>
      </region-specific>
    </display-properties>
    <execution-properties timeoutMs="7000" prepareTimeoutMs="3000"/>
    <!--
    <crawl-properties fullCrawlInterval="P5D" enableWcServicesCrawl="true"
                      enableWcDiscussionsCrawl="true" enableWcUcmCrawl="true"/>
    -->
    <ses-properties>
      <connection/>
      <data-group/>
    </ses-properties>
  </searchC:adf-search-config> 

45.3.3 Using the Search Java APIs

Custom components can implement search APIs to expose their content to WebCenter Portal's search.

For more information, see Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal.

45.3.4 Using the Search REST APIs

WebCenter Portal provides REST APIs that let you build a customized search user interface. With Oracle SES 11.2.2.2, you can use the search REST APIs to read (GET) searches and facets. Facets are returned with search results and can be used to filter the results. You can specify keywords and the scope of the search; for example, suppose a search for the term 'webcenter' produces thousands of results. A user could use facets (such as author or last modified date) in the URL to get the results for particular facet values, like author=Karen and last-modified-date=this week.

This section includes the following topics:

For an introduction to the REST APIs, see Chapter 53, "Using Oracle WebCenter Portal REST APIs."

45.3.4.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 search, find the link element with a resourceType of:

urn:oracle:webcenter:searchcollection

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

See Also:

There are two entries for search in the resource index:

  • urn:oracle:webcenter:searchcollection (This requires WebCenter Portal to be configured with Oracle SES 11.2.2.2.)

  • urn:oracle:webcenter:searchresults (This requires WebCenter Portal to be configured with Oracle SES--any supported version.)

This chapter describes only urn:oracle:webcenter:searchcollection. For detailed information about urn:oracle:webcenter:searchresults, see:

http://docs.oracle.com/cd/E28280_01/webcenter.1111/e10148/jpsdg_search.htm.

For more information about the resource index, see Section 53.5.1, "Using the Resource Index."

For more information about resource types, see Section 53.5.2.1, "Resource Type."

45.3.4.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 53.5.2.1, "Resource Type."

The taxonomy for the search is:

urn:oracle:webcenter:searchcollection
   urn:oracle:webcenter:searchcollection: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). The entry point returns all the results in searchcollection element. Query various components by specifying appropriate values in dataType argument.

Support for searchTerms, data, and dataType where dataType has one or more of the following values:

  • resultCount - number of results satisfying the query

  • results - actual results

  • facetCount - number of facets for the query result

  • facets - facets for the current results

Specify more than one dataType with comma separated values. For example:

http://host:port//rest/api/searchcollection?&dataType=results,facets
&facetParams=author:weblogic&utoken=FDX7xKPzzrnsbWRHNP-b-iUoWiJ4_w\*\\\\\\\\*

Navigation Paths to results

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

resourceindex
   searchcollection
resourceindex
   spaces
      spaces:resourceindex
         spaces:searchcollection

Supported Methods for results

The following methods are supported by this resource:

  • GET

    • request - body: none, Parameters: q, dataType, startIndex (pagination), itemsPerPage (pagination), data, facetParams

    • response - body: search results, and optionally facets

where:

  • q={queryString}

    Searches may be specified using the following format:

    [[field1:[operand]][:]value1[;field2:operand:value2]]
    

    Where multiple clauses are joined by an implicit AND and are syntactically separated by the ";" semicolon. Square brackets [] denote optional values. Each clause can be a keyword simple string with no ":" colon separator.

    The query string does not support anything other than a query keyword.

  • dataType is the type of results

    For example, if you want only results, then dataType=results (or left empty). To include facets in the results, then dataType=results,facets.

  • data is parameters for custom attributes

    For example:

    data=numberofreplies,wc_tagsWords
    
  • facetParams is parameters for facet refinement

    Default set is Service ID, scope GUID, Tags, Author, Last Modified Date, Mimetype.

    For example, to refine by people, set the facet Service ID only to oracle.webcenter.people:

    facetParams=Service%20ID:oracle.webcenter.people
    

Note:

If you want to use the facetParams parameter, then the dataType parameter must include facets.

Example 45-4 Search REST Commands

http://examplehost:8888/rest/api/searchcollection?q=document&utoken={utoken}

http://examplehost:8888/rest/api/searchcollection?q={keyword}
&data=dDocName,dOriginalName&dataType=results,facets
&facetParams=Service%20ID:oracle.webcenter.people

For more information, see Section 53.5.2.5, "Templates."

See Also:

For detailed information on Oracle SES query syntax, see:

http://docs.oracle.com/cd/E21698_01/admin.1122/e21605/search001.htm#BABFDAGD.

Writable Elements for results

Table 45-3 lists the writable elements for this resource.

Table 45-3 Writable Elements for results

Element Type Description

author

String

Any user who has written to the result

resourceId

String

Unique identifier

serviceId

String

Service ID of the result; for example, oracle.webcenter.doclib

title

String

Title of result

description

String

Description of result

modified

Date

Last modified date

size

Number

Size of result

docid

String

Document identifier

created

Date

Original author of result

icon

String

Icon for result type

url

String

URL of result

mimetype

String

Mimetype of result

guid

String

GUID value of result

scope

String

GUID value of the portal

scopename

String

Portal name

resourceType

String

Type of result

language

String

Language of result

snippet

String

Snippet of result

modifier

String

Modifier of result

customattributes

any

List of any custom attributes specified in data


Resource Types Linked to From results

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

Table 45-4 Related Resource Types for search

rel resourceType

self

 

45.3.4.3 Security Considerations

Authentication is required before using search REST API methods.

For general security considerations, see Section 53.8, "Security Considerations for WebCenter Portal REST APIs."

45.3.4.4 Search Resource Types

This section provides information about each resource type. It includes the following topics:

45.3.4.4.1 urn:oracle:webcenter:searchcollection:links

Use this resource type for template links and pagination links.

45.3.4.4.2 urn:oracle:webcenter:searchcollection:results

Use this resource type to identify the URI to use to read (GET) a query containing keywords and facets.

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.

45.3.4.4.3 urn:oracle:webcenter:searchcollection:facets

Use this resource type to identify the URI to use to read (GET) a query containing facets. Facets are returned with the query results and can be used to filter the results. Users can use these facets in the URL to get the results for particular facet values, like author=weblogic and last-modified-date=this week.

The request is represented by the URL and the response is a list of facets, 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.

45.3.5 Using the Search Data Control

Use the Search data control to build a customized search user interface with an 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 application Resource Catalog to build site templates.

45.3.5.1 Search Data Control Methods, Attributes, and Classes

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

Table 45-5 searchSes Input Parameters

Parameter Required? Type Description

scopeGuid

No

String

GUID value to filter results by portal.

serviceId

No

String

The service ID of the item; for example, oracle.webcenter.doclib searches only documents. If omitted, this searches across all tools and 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.

itemsPerPage

Yes

Integer

Number of results to display.


The searchSes method returns:

45.3.5.1.1 SearchServiceDCRows
  • author

  • comments

  • createDate

  • description

  • iconPath

  • language

  • largeIconPath

  • lastModifiedDate

  • resourceId

  • scopeGuid

  • serviceId

  • size

  • tagWords

  • title

  • type

  • urlSearchServiceDCRefiner

45.3.5.1.2 SearchServiceDCRefiner

element

45.3.5.1.3 SearchServiceDCRefinement
  • keywords

  • scopeGuid

  • serviceId

  • Collection of predicates

45.3.5.2 Integrating the Search Data Control

To use the Search data control:

  1. In JDeveloper, create an application with an Oracle SES connection. After the connection is available, the Search Data Control is listed in the Data Controls palette.

  2. Drag and drop the searchSes method from SearchServiceDC.

  3. Choose ADF Parameter Form, and the Edit Form Fields dialog opens. Click OK.

  4. Drag the rows accessor, from the SearchServiceDCResult return object type, onto the form, and choose Table - ADF Read-only Table. Click OK.

  5. Run the page, enter appropriate values. For example:

    • keywords: any search term

    • startIndex: 0

    • itemsPerPage: 10

For information about adding data controls to your application, see Section 4.1.2, "Understanding WebCenter Portal APIs."

45.3.6 Building Adapters for Search

You can use search adapters to add other sources to your search results. WebCenter Portal automatically discovers these search adapters and consolidates them in formulating search results in your application. Subsequently, when you expose your custom component to search 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 topics:

45.3.6.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 search.

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 ...

Note:

Oracle SES is set as the default search platform. For this sample code to work with WebCenter Portal's live search adapters instead, you must edit crawl-properties in adf-config.xml. For details, see Section 45.3.2, "Configuring Search with WebCenter Portal's Live Search."

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

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

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

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

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

      Figure 45-6 WebCenter Common Library

      Description of Figure 45-6 follows
      Description of "Figure 45-6 WebCenter Common Library"

    3. Click OK.

  3. Create a class called SampleQueryManager.java (Example 45-5).

    Example 45-5 SampleQueryManager.java

    package mycompany.myproduct.myapp.mycomponent.query;
    import java.util.List;
    import oracle.webcenter.search.QName;
    import oracle.webcenter.search.Query;
    import oracle.webcenter.search.QueryExecutor;
    import oracle.webcenter.search.QueryManager;
    import oracle.webcenter.search.Row;
    public class SampleQueryManager
      implements QueryManager
    {
      public SampleQueryManager()
      {
      }
      public QueryExecutor<Row> createRowQueryHandler(Query query,
                                                      List<QName> columns)
      {
        return new SampleRowQueryExecutor(query, columns);
      }
    }
    
  4. Create a class called SampleRowQueryExecutor.java (Example 45-6).

    Example 45-6 SampleRowQueryExecutor.java

    package mycompany.myproduct.myapp.mycomponent.query;
    import java.text.DateFormat;
    import java.text.ParseException;
    import java.text.SimpleDateFormat;
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.Iterator;
    import java.util.List;
    import java.util.Map;
    import static oracle.webcenter.search.AttributeConstants.DCMI_EXTENT;
    import static oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED;
    import static oracle.webcenter.search.AttributeConstants.DCMI_AUTHOR;
    import static oracle.webcenter.search.AttributeConstants.DCMI_TITLE;
    import static oracle.webcenter.search.AttributeConstants.DCMI_URI;
    import static oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER;
    import static oracle.webcenter.search.AttributeConstants.WPSAPI_ICON_PATH;
    import oracle.webcenter.search.QName;
    import oracle.webcenter.search.Query;
    import oracle.webcenter.search.QueryExecutor;
    import oracle.webcenter.search.QueryHandler;
    import oracle.webcenter.search.QueryResult;
    import oracle.webcenter.search.Row;
    public class SampleRowQueryExecutor
      implements QueryExecutor<Row>
    {
      private static final int PRESET_ESTIMATED_RESULT_COUNT = 10;
      private static final int PRESET_VALUES_BATCH_SIZE = 5;
      private static final int MAX_RESULT_LIMIT = 100;
      private int m_resultStart;
      private int m_resultLimit;
      private Query m_query;
      private List<QName> m_columns;
      private Map<String, String> m_properties;
      public SampleRowQueryExecutor(Query query, List<QName> columns)
      {
        m_query = query;
        m_columns = columns;
        m_properties = new HashMap<String, String>();
        // In actuality you may want to make sure this string is translatable
        m_properties.put(QueryHandler.TITLE, "Sample");
      }
      /**
       * Create several rows for "batchRepeat" times.
       */
      private static void createRows(List<Row> rows, int batchRepeat)
      {
        while (batchRepeat-- > 0)
        {
          rows.add(new SampleRow("23847", "Initial Sorting of Tables", 
                                 "Bar", "2006-06-08", 5120));
          rows.add(new SampleRow("4827445", "Support for facelets?", 
                                 "Foo", "2006-04-17", 1400000));
          rows.add(new SampleRow("952787", "For Thomas Kincade's validation demo", 
                                 "Tiger", "2006-01-09", 1300000));
          rows.add(new SampleRow("4394588", "Page not showing in WYSIWYG fashion",
                                 "Ken Swartz", "2006-04-27", 3000));
          rows.add(new SampleRow("3920", "Tree table", 
                                 "Scott", "2006-03-24", 1200));    
        }
      }
      /**
       * Instead of doing a query execution here, 
       * just create a bunch of rows.
       */
      public QueryResult<Row> execute()
      {
        List<Row> rows = new ArrayList<Row>();
        // To hit a certain count here but not go over the max
        int realLimit = Math.min(MAX_RESULT_LIMIT, m_resultLimit);
        createRows(rows, (realLimit / PRESET_VALUES_BATCH_SIZE));
        // Create the QueryResult
        QueryResult<Row> ret = new SampleRowQueryResult(rows.iterator());
        ret.getProperties().put(QueryResult.ESTIMATED_RESULT_COUNT, 
                                Integer.toString(PRESET_ESTIMATED_RESULT_COUNT));
        return ret;
      }
      /**
       * Remember the result start.
       */
      public void setResultStart(int resultStart)
      {
        m_resultStart = resultStart;
      }
      /**
       * Store away the result limit to use in the execute
       * to only get that number of results back.
       */
      public void setResultLimit(int resultLimit)
      {
        m_resultLimit = resultLimit;
      }
      /**
       * Expose our properties map containing our title.
       */
      public Map<String, String> getProperties()
      {
        return m_properties;
      }
    }
    
  5. Create a class called SampleRowQueryResult.java (Example 45-7).

    Example 45-7 SampleRowQueryResult.java

    package mycompany.myproduct.myapp.mycomponent.query;
    import java.util.Iterator;
    import oracle.webcenter.search.util.WrapperQueryResult;
    import oracle.webcenter.search.Row;
    public class SampleRowQueryResult extends WrapperQueryResult<Row>
    {
      public SampleRowQueryResult(Iterator<Row> rows)
      {
        super(rows);
      }
    }
    
  6. Create a class called SampleRow.java (Example 45-8).

    Example 45-8 SampleRow.java

    package mycompany.myproduct.myapp.mycomponent.query;
    import java.text.DateFormat;
    import java.text.ParseException;
    import java.text.SimpleDateFormat;
    import java.util.Calendar;
    import java.util.Date;
    import java.util.HashMap;
    import java.util.Iterator;
    import java.util.Map;
    import oracle.webcenter.search.QName;
    import oracle.webcenter.search.Row;
    import static oracle.webcenter.search.AttributeConstants.DCMI_EXTENT;
    import static oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED;
    import static oracle.webcenter.search.AttributeConstants.DCMI_AUTHOR;
    import static oracle.webcenter.search.AttributeConstants.DCMI_TITLE;
    import static oracle.webcenter.search.AttributeConstants.DCMI_URI;
    import static oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER;
    import static oracle.webcenter.search.AttributeConstants.WPSAPI_ICON_PATH;
    public class SampleRow implements Row
    {
      private Map<QName, Object> m_storage = new HashMap<QName, Object>();
      private DateFormat m_dateFormat = new SimpleDateFormat("yyyy-MM-dd");
      SampleRow(String id, String title, 
                String author, String lastModified,
                int size)
      {
        m_storage.put(DCMI_IDENTIFIER, id);
        // Only if you have an external URL to go to
        // m_storage.put(DCMI_URI, "http://my.external.url");
        m_storage.put(DCMI_TITLE, title);
        m_storage.put(DCMI_AUTHOR, author);
        // The below path points to a path accessible in the classpath to an icon
        m_storage.put(WPSAPI_ICON_PATH, "/adf/webcenter/search_qualifier.png");
        try
        {
          Date date = m_dateFormat.parse(lastModified);
          Calendar cal = Calendar.getInstance();
          cal.setTime(date);
          m_storage.put(DCMI_MODIFIED, cal);
        }
        catch (ParseException e)
        {
          e.printStackTrace();
        }
        m_storage.put(DCMI_EXTENT, new Long(size));
      }
      public Object getObject(QName columnName)
      {
        return m_storage.get(columnName);
      }
      public Iterator<QName> getColumns()
      {
        return m_storage.keySet().iterator();
      }
    }
    

45.3.6.2 How to Register a Custom Adapter

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

The entry should be similar to Example 45-9.

Example 45-9 Sample Query Manager Entry in service-definition.xml

<service-definition id="mycompany.myproduct.myapp.mycomponent"
   version="11.1.1.0.0">
  <resource-view taskFlowId="/somepath/somefile.xml#someId"
                    authorizerClass="some.service.id.Authorizer1"/>
  <name>Custom Component 1</name>
  <description>Description for Custom Component 1</description>
  <search-definition xmlns="http://xmlns.oracle.com/webcenter/search"
      id="mycompany.myproduct.myapp.mycomponent.query" version="11.1.1.0.0">
  <query-manager-class>
mycompany.myproduct.myapp.mycomponent.query.SampleQueryManager
  </query-manager-class>
  </search-definition>
</service-definition>

For more information about the resource-view tag (and WebCenter Portal's Resource Action Handling framework), see Section 4.3, "Customizing How Services Render Resources."

45.3.6.3 Search Adapter Attributes

This section describes the attributes available for searching. It includes the following topics:

45.3.6.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.6.3.8, "Selectable Attributes."

45.3.6.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. Search 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.6.3.3 Date Condition

For search 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.6.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_THAN AttributePredicate and one LESS_THAN AttributePredicate 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.6.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.6.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.6.3.7 Access

Search (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.6.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 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 search 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>.

    Search 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. Search 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 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 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 components, such as documents and pages, 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 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.

  • Author

    For each resource returned, the search user interface can display the author 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_AUTHOR and AttributeConstants.WPSAPI_MODIFIED, respectively. The author is of type java.lang.String.

  • Icon

    For each resource returned, the search 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 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.6.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.

WebCenter Portal's search invokes a resource viewer using the Resource Action Handling framework. For information about registering a resource viewer to allow custom components to be found using search, see Section 4.3, "Customizing How Services Render Resources."

45.3.7 Customizing the Search UI Without WebCenter Portal's Search APIs

You can develop a custom search user interface in an application without WebCenter Portal's search 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.

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

    See Also:

    "Setting Up Oracle SES to Search Documents" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal

    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
    
  2. 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.

  3. Specify WebCenter Portal's Resource Action Handling class for click action of search result.

    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.

    Example 45-10 Specifying PopUp Behavior Handler

    xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
      <wpsC:adf-service-config xmlns="http://xmlns.oracle.com/webcenter/framework/service">
        <resource-handler class="oracle.webcenter.framework.resource.view.PopUpResourceActionHandler"/>
      </wpsC:adf-service-config>
    

    Example 45-11 shows how to use NavigationResourceActionHandler to show the resource in the navigation node of the resource when a search result is clicked.

    Example 45-11 Specifying the Navigation Handler

    xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
      <wpsC:adf-service-config xmlns="http://xmlns.oracle.com/webcenter/framework/service">
        <resource-handler class="oracle.webcenter.portalframework.sitestructure.handler.NavigationResourceActionHandler"/>
      </wpsC:adf-service-config>
    

45.3.8 Troubleshooting Search

This section describes common problems and solutions for search.

Problem

There is a set timeout for querying each component. If a particular component does not return search results in the allotted time, then it times out. Announcements and discussions are susceptible to timeouts. Pages and portals also 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.