Unleashing the power of WebSphere Portal V6 Search with the Portal Search Toolbox

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Intermediate

David Konopnicki (DAVIDKO@il.ibm.com), Manager, Search Technologies Development, IBM　
Eitan Shapiro (EITANS@il.ibm.com), Software Engineer, IBM　

10 Jan 2007
Updated 30 Jul 2007

Do you want to empower your portal users with productive and advanced search capabilities such as suggested links or faceted search navigation? You can do just that with the Search and Indexing API (SIAPI) , published for IBM® WebSphere® Portal V6.0. This article describes how you can use seven sample portlets to enrich the end-user’s search experience, and to increase your portal’s administrative capabilities as well. You can download the sample portlets and run them as-is, or you can modify the sample source code as needed. Using these sample portlets on a portal page shows you how to provide a richer search experience for your portal.

Introduction

WebSphere Portal V6.0 features the Search and Indexing API (SIAPI) which enables you to build portlets that customize the search experience in a portal. This article introduces seven sample portlets that use SIAPI. See the Resources section to download the sample portlets and to get additional information about SIAPI, including the Javadoc.

The sample portlets serve two purposes: they demonstrate the flexibility of the search interfaces, and they provide advanced search features to enhance the search experience of your portal site. The Portal Search Toolbox (PST) includes these sample portlets:

• Scope Search – searches in a pre-defined search scope only
• Display Results – displays a list of search results
• Searchlet – displays search results from an external search service like Yahoo!
• Sponsored Links – displays a list of suggested links based on keywords entered in the search request
• Facets – filters a list of search results using available facets (for example: author, date) that appear in the search results
• Advanced Search – queries a scope using advanced search options (for example: search by author, title and so on.)
• Search History – enables administrator and/or users to browse the history of their queries and the results they clicked

None of the PST portlets work in isolation. Instead, they integrate with search using portlet wiring to provide the user a rich search experience. Therefore, you can place the relevant portlets on a portal page as needed, providing a seamless search experience for your users and data. (See the example in Figure 1 .)

This article provides information about each PST portlet, how to deploy and configure each portlet, and also shows an example of how you can wire the portlets together to enable the overall search experience.

To use the PST portlets, you need to have installed WebSphere Portal V6.0 and the Ifix PK32675.

Back to top

Introducing the PST sample portlets

This section describes the purpose and possibles uses of each of the PST portlets. It tells, how to configure them, and describes their wiring capabilities and options.

Back to top

Scope Search

You can use the Scope Search portlet to provide a query search user interface with three elements: the text area for query input, the search button to execute the query, and a search scope selection list.

This portlet works in conjunction with other portlets from the PST, such as the Display Results portlet to render the search result list that results when executing a query through this portlet. Figure 2 shows the Scope Search portlet.

You can find this portlet in pst.scopesearch.war.

Configuring Scope Search

In configuration mode, or through the Scope Search portlet parameters, you can configure two parameters:

• ResultSet Size – defines the number of results to retrieve from the scope. The default is 100.
• Results per Page – defines the number of results displayed per page in the Display Results portlet. The default is 10.

Results per Page and ResultSet Size are straightforward for general searches. When you are using the Scope Search portlet in conjunction with the Facets portlet, the ResultSet Size determines the number of results that create the aggregated data for displaying the facets (for more information, see the Facets section).

For example, you can choose to display ten results in the Display Results portlet, but, in the background, use the ResultSet Size to request at least one hundred results. This provides the Facets portlet with more selections to use for filtering of the search result; users can see the first ten results, but can also filter the search results using the authors that appear in the whole result set (100 in this example). The more results you request, the slower the results display.

Wiring Scope Search

The Scope Search portlet uses several wires to communicate with the other PST portlets. The ‘Wiring Options’ section presents all the available wires.

The Scope Search portlet generates the following messages:

• Results – contains the query, the searched scope identifier, and the results list. For example, this message is consumed by the Display Results portlet
• Scope Change – contains the selected scope.

The portlet consumes the following messages:

• Source – contains the information necessary to query for the next or previous page of results.
• Query Extend – contains advanced search conditions that can be added to the full text query.

Back to top

Display Results

You can use the Display Results portlet to display a list of search results where the search was initiated by either the the Scope Search portlet (the results of a search), the Facets portlet (the results filtered by a selected facet), or the Search History portlet (the results clicked in the past or some search query that was saved in the history recordings and is being reissued). Figure 3 shows the

When a user clicks an item in the search result, an event is passed to the Search History portlet (if present on the page and wired) so the user can see the list of links clicked for any query in the history.

You can find this portlet in pst.searchresults.war.

Configuring Display Results

In configuration mode or through the portlet parameters, it is possible to define whether:

• The results open in a new window. Default is ‘0’ (false).
• The portlet displays a message when initially placed on a page. Default is ‘1’ (true). This is useful if you want to put several Display Results portlets in one page and want to hide this from your users.
• The portlet highlights search terms in any part of the search results. Default is true.

Wiring Display Results

The Display Results portlet generates the following messages:

• Link Click – conveys that a search result has been clicked.
• Source – computes the next or previous page of results to display.

This portlet consumes the following messages:

• Results – the search results to display.
• Clicked Results – the list of clicked results for a given query saved in the history.

Back to top

Searchlet

You can use the Searchlet portlet to display the search results obtained from various other internal or external search services. This way, it is possible to compose a screen showing the main portal results alongside search results from other search applications or services. Figure 4 shows the Searchlet portlet on the right side.

You can find this portlet in pst.searchlet.war.

Configuring Searchlet

The Searchlet portlet accesses the search service through an HTTP URL. In configure mode, you can configure the Searchlet by uploading an XML file that describes the search service to the portlet. The Searchlet portlet parses this XML file and saves the different configuration parameters as portlet parameters.

Listing 1 gives an example of such a configuration file; this file is used to query www.ibm.com:

                
<search action="http://www.ibm.com/Search/">
<input name="q"/>
<interpret
resultListStart="<!--BeginOutput-->"
resultListEnd="<!--EndOutput-->"
resultItemStart="<td width="392"valign="top" dir="ltr">"
resultItemEnd="<!--EndRecord-->"
/>
</search>

This format is a slight variation from the mycroft format (http://mycroft.mozdev.org/):

• <search action=”…”> specifies the URL of the search service.
• <input input=”…”> specifies the URL parameter for the query.Thus the actual web interface is http://www.ibm.com/Search/?q=
• resultListStart is the marker for the start of the search results in the HTML page returned as the result.
• resultListEnd is the marker for the end of the search results.
• resultItemStart and resultItemEnd identify each search result item respectively.

You must set the portlet parameter search_engine to value com.ibm.lotus.search.pst.mycroftengine.impl.MycroftEngineImpl.

You can configure additional portlet parameters, including:

• URL of the image to display on top of the results (banner_uri).
• Number of results to display (max_number_of_results). Default is 5.
• Whether or not the portlet displays a message when there are no results (display_result_info_message). Default is true.

Wiring Searchlet

The Searchlet portlet consumes the Results message and uses the query part of it to issue the same query against the external search service.

Important:

• This portlet does not take into account the part of the query defined in the Advanced Search portlet, if any.
• This portlet does not save the clicks in this portlet to the Search History portlet.

Back to top

Sponsored Links

Like the Searchlet portlet, you can use the Sponsored Links portlet to display search results alongside the portal results. However, in this case, the administrator manually defines the results using a dedicated Portal Search collection. The administrator can use this portlet to map select search results to certain keywords in the user’s search request. If the user does not enter these keywords, then the Sponsored Links portlet returns no links. Figure 5 shows the Sponsored Links portlet.

This portlet is also a solution for site administrators to promote certain links without tampering with the relevancy logic of the search engine by adding term weights to certain keywords. Because the portlet is separate from the regular search results, its presence is acceptable to end-users.

You can find this portlet in pst.searchlet.war.

Configuring Sponsored Links

The basic concept for using this portlet is to create and use a search collection built for the purpose of retrieving a list of URLs based on a search that typically searches only in the ‘keyword’ fields of the indexed content. You associate keywords with a given URL manually using the ‘Add document’ feature of the search collection (not by crawling the sponsored Web site).

You add URL references to your sponsored links through the Search Admin portlet. First, you create a collection for your sponsored links by selecting Administration > WebSphere Portal > Search Administration > Manage Search (see the WebSphere Portal Infocenter for detailed information).

Once you create your collection, you define a sponsored link in your collection by clicking the Add Document icon ().

In the subsequent screens, you define the URL for a sponsored link and associate keywords with the URL for this search collection.

The content of the page is also indexed in the collection. Using the portlet parameters, you can configure the Sponsored Links portlet to search either the content or the keywords for the user's query.

You must set the portlet parameters:

• search_engine to value com.ibm.lotus.search.pst.sponsoredlinkssearch.impl.SponsoredLinksSearch
• search_displayer to value com.ibm.lotus.search.pst.sponsoredlinkssearch.impl.SponsoredLinksDisplayer

This portlet is the same as the Searchlet portlet but uses different parameters.

You can configure additional portlet parameters, including:

• URL of the image to display on top of the results (banner_uri).
• Number of results to display (max_number_of_results). Default is 5.
• Collection containing the sponsored links (collection_id).
• Whether or not the portlet displays a message when there are no results (display_result_info_message). Default is true.
• Whether the page content should be searched or only keywords (use_content)

Wiring Sponsored Links

The Sponsored Links portlet consumes the Results message and uses the query part of it to issue the same query against the sponsored links collection.

Back to top

Facets

Faceted search and navigation is a new search paradigm that facilitates locating and filtering search results. You can use the Facets portlet to automatically organizes search results through multiple categorization schemes. The portlet computes the categories, or “facets,” automatically, based on the most frequent attribute values of a set of results (See Figure 6 ) and displays them to the user. Beside the facet value, within parentheses, is the number of matches from the results set that have this specific value.

For example, in Figure 6, the result set contain 100 results. If you look at the ‘Source’ facet, you’ll see that 95 results are Portal Pages, 1 is a Web page and 4 are from another source. When you click on one of the values, the portlet refreshes the result set and the facets to show only the result set that contains the items that match the selected value. If you click on the Portal Page link, all of the facets refresh to show the facets relevant to the 95 Portal Pages.

You can find this portlet in pst.facetsearch.war.

Configuring Facets

In configure mode, you can configure the Facets portlet by defining:

• Default Facet – the comma-delimited list of the default facets to display.
• Facets Text Field – the comma-delimited list of additional result attributes to add to the facets. For example, if your results contain an additional metadata field called Media, you can add this field to the list of facets by putting Media in this configuration list.
• Results per page – the number of search results to display in a page when a facet is clicked.

Wiring Facets

The Facets portlet communicates with the Display Results portlet in order to display only the results that belong to the currently clicked facet.

The Facets portlet generates the Results message, which contains the results of the filtering for the current facet. This portlet consumes the Results message in order to compute the current facets.

Back to top

Advanced Search

You can use the Advanced Search portlet to define advanced search conditions. Because different fields can be relevant for different scopes, for every search scope, this portlet shows the list attributes for which it is possible to define a condition (for example: author, title). For a given attribute, you can define the search value either as free text, or by selecting a value from a list based on what you defined in configuration mode. See Figure 7 .

The Advanced Search portlet communicates with the Scope Search portlet so that when the user clicks the Search button in the Scope Search portlet, the browser submits the advanced search conditions, together with the search keywords, to the search engine.

You can find this portlet in pst.advancedsearch.war

Configuring Advanced Search

Configuring the Advanced Search portlet requires two steps. First, you create a document library that stores the advanced search attributes and optional values. Second, you configure the Advanced Search portlet itself.

To create the document library, which saves the portlet’s advanced search information:

1. Go to Portal Administration > Portal Content > Document Libraries.
2. Click New document library.
3. Type a library name and click Create.

Remember to write down the library's ID. This library ID is required later on as the value of the ADVANCED_SEARCH_DOC_LIB_ID portlet parameter.

The next step is to update the portlet’s configuration parameters: update ADVANCED_SEARCH_DOC_LIB_ID with the library ID of the newly created document libray.

In edit mode of the portlet (see Figure 8 ), for each scope, you can define which attributes display and whether the user can enter each attribute as free text,or can select the attribute from a list of values.

Wiring Advanced Search

The Advanced Search portlet generates the Query Extend message, which contains the advanced query terms that need to be added to the full-text query.

This portlet consumes the following messages:

• Scope Change – to update the available filters for a given scope.
• Results – to display the correct filters for a given query (issued, for example, by the Search History portlet).

Back to top

Search History

You can use the Search History portlet (see Figure 9 ) to save the search queries that a user issues. In addition, for each query, it saves the links from the clicked search results. To see the links, click the icon in the Clicked Results column. Clicking on a query re-issues it.

You can find this portlet in pst.searchhistory.war.

Configuring Search History

To use the Search History portlet, first create a document library where the portlet can save the queries:

1. Select Portal Administration > Portal Content > Document Libraries.
2. Click New document library.
3. Type a library name and click Create.

Record the library's ID; you can use the ID to find the library at runtime.

The Search History portlet has three configuration parameters:

• Queries Per Page – the number of history queries displayed per page.
• Queries Per User – the maximum number of queries to store for each user.
• Search History Document Library ID – the ID of the document library used to store the history.

Wiring Search History

The Search History portlet generates the following messages:

• Source – passes on a saved query that can be re-issued.
• Clicked Results – passes on the saved results for a given query to be displayed.

This portlet consumes the following messages:

• Results – to save the current query.
• Link Click – to save the results that were clicked.

Back to top

Wiring Options

Table 1 presents all the wiring options for the PST portlets, including the source portlet, the target portlet, and the description of each wiring. The description also shows which output of the source portlet connects to which input of the target portlet, in parentheses.

Back to top

Configuring the PST portlets for anonymous user access

1. Login into the WebSphere Admin console (server1).
2. Goto Resources => Resource environment providers and find the WP NavigatorService service.
3. On the Configuration tab, under Additional Properties, find the Custom properties section and add this new property:

   public.session=true

   
   
4. Start WebSphere Portal.
5. In the <portalserver>/config/properties directory, edit the file PortletServiceRegistryService.properties. Find the following line, and make sure it is uncommented; if it is not, then remove the leading # sign. If you don't find this line, then add it; although the line below displays across two lines, place it all on one line in the PortletServiceRegistryService.properties file.

   com.ibm.wps.propertybroker.standard.service.PropertyBrokerServiceWrapper.com.ibm. portal.propertybroker.standard.anonymous.page.support = true

   
   
6. On the command line, run this command:

   <portalserver>/config/WPSconfig.bat update-properties

   
   
7. Restart WebSphere Portal.

Back to top

Conclusion

This article presents the sample portlets included in the Portal Search Toolbox. Experiment with these sample portlets, examine their code, and customize them according to your needs.

Back to top

Acknowledgements

The authors wish to thank and acknowledge the following people for their contributions and time spent in writing and testing those sample portlets:

• Bob Barber for the Scope Search portlet, the Facets and the Display Results portlet.
• Amir Skovronik for the Searchlet portlet.
• Constantin Radchenko for the Sponsored Links portlet.
• Ann Hayes for the Facets portlet.
• Dan Shacham and Shai Erera for the Advanced Search portlet.
• John Kilroy for the Search History portlet.
• Alex Song for his helpful comments on the user experience.
• Batya Frostig for testing the portlets.

The authors wish to thank Andreas Prokoph for his helpful comments.

Resources

• IBM Search and Index APIs (SIAPI) for WebSphere Information Integrator OmniFind Edition
  
  
• IBM Search and Index (SIAPI) V6.0 Javadoc
  
  
• Introducing the Search and Indexing API in WebSphere Portal V6.0
  
  
• Portlet Development Workbook
  
  
• Search WebSphere Portal Document Manager using WebSphere Information Integrator OmniFind Edition
  
  
• WebSphere Information Integrator Omnifind Edition
  
  
• WebSphere Information Integrator zone
  
  
• WebSphere Portal product documentation
  
  
• WebSphere Portal zone
  
  
• What’s new in WebSphere Portal Version 6?

• Download the Portal Search Toolbox sample portlets.
  
  
• Download Ifix PK32675 for WebSphere Portal V6.
  
  

About the authors

		David Konopnicki manages the Search Technologies department of the IBM Haifa Research Lab, which develops the full-text search engines embedded in IBM Lotus Collaboration products and IBM WebSphere Portal. David has 6 years of experience in Research and Developement of Search Engines, Search Applications, Databases and Electronic Commerce.

		Eitan Shapiro holds a BSc degree in Information Systems Engineering from the Technion, Haifa, Israel. He joined IBM in 2005, and he is the chief programmer of the Haifa Search Technologies Team.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top